# Plaid Technical Documentation - Full Version # Complete version - for LLMs with sufficient context capacity # Summary version: https://plaid.com/docs/llms.txt # Full plaid.com site index: https://plaid.com/llms.txt --- # Home | Plaid Docs Welcome to the Docs  ==================== #### Here you'll find guides, resources, and references to build with Plaid.  (An image of "Decorative image of a Abe Lincoln enjoying an energy drink") #### Quickstart  Learn about Plaid's key concepts and run starter code [Get started](https://plaid.com/docs/quickstart/index.html.md) #### API Reference  Explore server-side API libraries and integrate with API endpoints [View reference](https://plaid.com/docs/api/index.html.md) #### Link  Link, Plaid's client-side component, helps your users connect their accounts [Build with Link](https://plaid.com/docs/link/index.html.md) #### Payments and Funding  #### Auth  [Retrieve bank account information for ACH, wire, and other bank-to-bank transfers.](https://plaid.com/docs/auth/index.html.md) #### Balance  [Retrieve real-time balance information to prevent ACH returns.](https://plaid.com/docs/balance/index.html.md) #### Identity  [Verify users' financial account ownership and reduce fraud.](https://plaid.com/docs/identity/index.html.md) #### Signal Transaction Scores  [Reduce fraud and provide instant funds access by assessing the return risk of an ACH debit transaction.](https://plaid.com/docs/signal/index.html.md) #### Transfer  [Send and receive money end to end with Plaid.](https://plaid.com/docs/transfer/index.html.md) #### Investments Move  [Get verified data for initiating an ACATS or ATON brokerage-to-brokerage transfer.](https://plaid.com/docs/investments-move/index.html.md) #### Payments (Europe)  [Make one-time payments, recurring payments, or payouts within your app.](https://plaid.com/docs/payment-initiation/index.html.md) #### Financial Insights  #### Transactions  [Retrieve transaction data for budgeting tools, expense management, and more.](https://plaid.com/docs/transactions/index.html.md) #### Investments  [View holdings and transactions from investment accounts.](https://plaid.com/docs/investments/index.html.md) #### Liabilities  [Access loan data, like balances and interest rates, for student loans, mortgages, and credit cards.](https://plaid.com/docs/liabilities/index.html.md) #### Enrich  [Add detailed information and insights to your existing transactions data.](https://plaid.com/docs/enrich/index.html.md) #### KYC, AML, and anti-fraud  #### Identity Verification  [Global KYC compliance and anti-fraud. Verify user identity data and documents.](https://plaid.com/docs/identity-verification/index.html.md) #### Monitor  [Use with Identity Verification to enable sanction, PEP, and watchlist screening for anti-money laundering compliance.](https://plaid.com/docs/monitor/index.html.md) #### Beacon  [Join the Plaid anti-fraud network](https://plaid.com/docs/beacon/index.html.md) #### Protect  [Prevent fraud before it happens — at every step of the user lifecycle.](https://plaid.com/docs/protect/index.html.md) #### Instant Onboarding  #### Layer  [Onboard users instantly with just a phone number.](https://plaid.com/docs/layer/index.html.md) #### Credit and Underwriting  #### Consumer Report (by Plaid Check)  [Make smarter credit and lending decisions with insights powered by Plaid Check.](https://plaid.com/docs/check/index.html.md) #### Assets  [Access users' financial information for loan underwriting.](https://plaid.com/docs/assets/index.html.md) #### Statements  [Get PDF statements directly from the user's bank, for underwriting verification and compliance.](https://plaid.com/docs/statements/index.html.md) #### Income  [Verify income and employment, for lending use cases and more.](https://plaid.com/docs/income/index.html.md) --- # Account - Activity, logs, and status | Plaid Docs Dashboard logs and troubleshooting  =================================== #### Discover logging and troubleshooting information available in the Plaid Dashboard  #### Logs for webhooks, Link, and API requests  The Plaid Dashboard [Activity Log](https://dashboard.plaid.com/activity/usage) shows the past 14 days of API activity. Using the dashboard, you can see a record of all requests and responses, as well as all webhooks sent by the Plaid API, and all Link events. (An image of "Plaid API logs showing request types, descriptions, institutions, environments, timestamps, and response codes in a dashboard.") You can view the details of any request, response, webhook, or event, and view error information for any failed API request. (An image of "Request and response details for failed API call: invalid public token expired. Error code 400, Halifax, Bank API, success rate 100%.") ##### Link analytics  The [Link analytics](https://dashboard.plaid.com/link-analytics) page in the Dashboard shows a summary of Link conversion, along with top Link errors your users are experiencing and recommendations for increasing conversion. For more details, see [Link conversion](https://plaid.com/docs/link/best-practices/index.html.md) . #### Logs for billable activity  The Plaid Dashboard [Usage Page](https://dashboard.plaid.com/activity/usage) shows billable API usage for most Plaid products. Usage data is also available via the Plaid MCP server, allowing you to interact with this data via chat or an LLM agent. For more details, see the [blog post on the Plaid Dashboard MCP server](https://plaid.com/blog/plaid-mcp-ai-assistant-claude/) and the [Plaid Dashboard MCP server documentation](https://plaid.com/docs/resources/mcp/index.html.md) . #### Logs for Payment Initiation, Transfer, and Signal  The Payment Initiation (UK and Europe), Transfer, and Signal products also have their own logs in the Plaid Dashboard. If you are enabled for these products, links to view activity will appear in the Products menu within the dashboard. Using these logs, you can view the status and history of payment and transfer attempts, returns, and other product-specific information. For Payment Initiation and Transfer, this information is also available via the API; for more details, see the API documentation for [Payment Initiation](https://plaid.com/docs/api/products/payment-initiation/index.html.md) and [Transfer](https://plaid.com/docs/api/products/transfer/index.html.md) . #### Audit logs  Audit logs of activity occurring in the Dashboard is available to admins on teams with Premium Support Packages. To learn more about upgrading to a Premium Support Package, contact your account manager. Dashboard audit logs include user identity, action type, IP address, and timestamps for core Dashboard actions. Audit log support for actions on product-specific Dashboard pages is not yet available. #### Troubleshooting institution status  The Plaid Dashboard contains an [Institution Status](https://dashboard.plaid.com/activity/status) pane, which allows you to view details and stats about institution connectivity over the past two weeks, as well as any recent downtime or special notes about the institution. You can also use this view to search institutions to see whether they are supported by Plaid and which Plaid products can be used with them. Most of this information is also available via the API; for more information on programmatically retrieving institution status, see [Institutions API endpoints](https://plaid.com/docs/api/institutions/index.html.md) . ##### Institution status details  (An image of "Plaid status for a bank: Auth 100%, Identity 100%, Transactions 100%. Historical graph of item add success. All products 100% success rate.") The graph at the top of the page shows institution status over the past two weeks, while the boxes below the graph show the current institution status. The time range used for calculating the current institution status may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. Plaid displays both Item add success rates (success adding new Items) and Item update success rates (success refreshing data for existing Items). The success rate as shown on the [main status page](https://dashboard.plaid.com/activity/status) is the Item add success rate. All success rates reflect the percentage of successful attempts to retrieve data. Both Plaid errors and institution errors are combined when calculating the percentage of unsuccessful attempts. User errors, such as an Item add failing due to an incorrect password entered during Link, are not considered when calculating success rates. All success rates are rounded down to the nearest percentage point. A success rate of 99% or higher indicates that the institution is considered healthy. ##### Institution migration status  Within the Institutions Status page, you can use the [migration pane](https://dashboard.plaid.com/activity/status) to view the status of OAuth migrations. The migration pane shows all institutions with planned or current migrations and allows you to drill in to see the migration timeline and the impact on existing Items. (An image of "Plaid migration status for a bank, in progress, type: Classic to API, timeline displayed.") ##### Insufficient data and delayed data  If the institution has not had enough Plaid traffic during the window being evaluated to produce meaningful health data, the "Insufficient Data" message will be displayed. This is most likely to affect small institutions. If this occurs, try using the [Item Debugger](https://dashboard.plaid.com/activity/debugger) instead to diagnose the problem. If Plaid has not been able to update data from the institution for over two days, the institution status may appear as "delayed". If it has been at least two weeks since the last successful institution update, or if Plaid is aware of a problem in updating data that is likely to take over two weeks to resolve, the institution status will appear as "stopped". ##### Alerting  You can set up alerts to be notified of changes to the global Item add success rate of any institution. From [Settings > Team Settings > Communications](https://dashboard.plaid.com/settings/team/notification-preferences) , open the "Status alerts" tab to create an alert. You can also create an alert directly from the institution's status page. If you choose webhook-based alerting, the webhook that will be sent is the [INSTITUTION\_STATUS\_ALERT\_TRIGGERED](https://plaid.com/docs/api/institutions/index.html.md#institution_status_alert_triggered) webhook. #### Troubleshooting with Item Debugger  To view the status of a specific Item or Link session in the dashboard, you can use the [Item Debugger](https://dashboard.plaid.com/activity/debugger) . You can look up Items and Link sessions by `client_user_id`, `item_id`, `access_token`, `link_token`, or `link_session_id`. Troubleshooting information available includes error codes and suggested troubleshooting steps you can take to resolve any errors. Access to the Item Debugger is also available via Plaid's Dashboard MCP server, allowing you to troubleshoot Item details via LLM chat or an agent. For more details, see the [blog post on the Plaid Dashboard MCP server](https://plaid.com/blog/plaid-mcp-ai-assistant-claude/) and the [Plaid Dashboard MCP server documentation](https://plaid.com/docs/resources/mcp/index.html.md) . (An image of "Item debugger showing a healthy item for institution Juno with an ID, transactions updated 5 hours ago.") --- # Account - Pricing and billing | Plaid Docs Plaid pricing and billing  ========================== #### Learn about pricing, what is considered a billable event, and how to monitor your bill  #### Pricing information  A price list is not available in the documentation. **To view pricing, [apply for Production access](https://dashboard.plaid.com/overview/request-products) . Pricing information for Pay as you go and Growth plans will be displayed on the last page before you submit your request.** For Custom plans, select the Custom option and submit the form, and sales will reach out to discuss pricing. Or, you can [contact sales](https://plaid.com/contact/) to learn more about custom pricing. #### Pricing plans  Plaid offers four types of pricing plans: * **Trial** – Free access. Limited to 10 Items; upgrade to a paid plan to access more Items. Most appropriate for hobbyist use, or for evaluating and learning more about Plaid. * **Pay as you go** – No minimum spend or commitment. Most appropriate for hobbyist use, or for early stage small businesses without validated business models or investment capital. * **Growth** – Minimum spend, annual commitment. Lower per-use costs than Pay as you go plans; includes business-focused features such as SSO, priority support, and a personal account manager. Most appropriate for small to medium size businesses with API usage volumes up to $6,000/month. * **Custom (aka Scale)** – Higher minimum spend and annual commitment but provides access to the lowest per-use costs. Minimums can apply across the entire Plaid account or by product and can apply across both Plaid and Plaid Check. Most appropriate for businesses with API usage volumes over $2,000/month or that require enterprise-level functionality. For a Custom plan, [contact sales](https://plaid.com/contact/) . To change your plan, see [Viewing or changing pricing plans](https://plaid.com/docs/account/billing/index.html.md#viewing-or-changing-pricing-plans) . For customers based in the EU or UK, or who will be serving end users based in the EU or UK, only Custom plans are offered. In addition, the following products are only offered via Custom plans: * Signal Transaction Scores * Transfer * Document Income with bank statements support * All Plaid Check products except for Base Reports and Income Insights Reports\* * Payment Initiation and Virtual Accounts * Layer (pre-GA; contact sales for details) * Protect (pre-GA; contact sales for details) \*No Plaid Check products are available on Pay as you go plans. Base Reports and Income Insights Reports are available via either Growth or Custom plans. All other Plaid Check products (LendScore, Partner Insights, Network Insights, etc.) are available via Custom plans exclusively. #### Trial plans  Free Trial plans are available to new Plaid teams (US/Canada only) created on or after April 15, 2026. Using a Trial plan, you can use Plaid with real production data for free. To start a Trial plan, [create a Dashboard account](https://dashboard.plaid.com/) and verify your email address. You can then access the Trial plan application form via the button on the Dashboard homepage or by going directly to [https://dashboard.plaid.com/trial-plan](https://dashboard.plaid.com/trial-plan) . ##### Trial plan limitations  You can create 10 Production Items on a Trial plan. After creating 10 Items in Production, you must upgrade to a paid plan to create more Production Items. Removing Items created on a Trial plan (using [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) ) will _not_ allow you to create more Items. When using a Trial plan, be sure to persist your access tokens and do not lose track of them. All access tokens created in Production will count against your Trial plan Item limit. The following products are available via Trial plans: * Assets * Auth * Balance * Identity * Investments (including Investments Refresh) * Liabilities * Transactions (including Transactions Refresh) * Statements If you added a [subscription fee](https://plaid.com/docs/account/billing/index.html.md#subscription-fee) product (such as Investments, Liabilities, or Transactions) to an Item during your trial, upon upgrading to a paid plan, you will begin to be charged for that subscription. Trial plans do not currently support Fidelity or Charles Schwab. For other institutions, OAuth access is typically granted instantly, but may take up to 24 hours at certain institutions. #### Pricing models  Plaid has multiple different pricing models, depending on the product. These models only apply to Production traffic; usage of Sandbox is always free. Note that the details outlined below are general information and guidance about typical pricing structures and policies for new customers. Your specific pricing and billing structure is governed by your agreement with Plaid. If you have questions about your bill, [contact support](https://dashboard.plaid.com/support/new/admin/account-administration/pricing) . Endpoints that are not associated with any particular product are typically available to Plaid customers free of charge. Examples of these free-to-use endpoints include [Institutions endpoints](https://plaid.com/docs/api/institutions/index.html.md) , [Item endpoints](https://plaid.com/docs/api/items/index.html.md) , [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) (not to be confused with [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) , which is associated with the Balance product), and [user management endpoints](https://plaid.com/docs/api/users/index.html.md) . ##### One-time fee  Products that use one-time fee pricing are: * Auth * Identity * Income (except for [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) , which uses per-request pricing) * Layer You will incur charges for one-time fee products whenever the product is successfully added to an Item. This occurs when an Item has been successfully created by Link and this product was specified in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . An Item is typically considered to be successfully created if a `public_token` was exchanged, but sometimes (e.g. when using micro-deposit Auth flows, or the in-Link Identity Match flow) it may be considered created once the `public_token` was created. If the Item was not initialized with the product at the time of creation, the product can also be added to the Item later by calling a product endpoint belonging to that product on the Item. For one-time fee products, it does not matter how many API calls are made for the Item (or user); the cost is the same regardless of whether the product's endpoints are called many times or zero times. For the Auth and Identity products, if the product was added to the Item via the `optional_products` parameter in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call, you will not incur charges for those products until their corresponding endpoint is called. For example, if you initialize an Item with `auth` in the `products` parameter and `identity` in the `optional_products` parameter, you will not be charged for Identity on that Item until you call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) or [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) for that access token. Note: Identity Match is a Per-request flat fee product, so calling [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) multiple times will result in repeated charges for Identity Match, but only one charge for Identity. For Document Income and Payroll Income, charges will be incurred when data is available to be accessed. This will typically be indicated by the `INCOME_VERIFICATION` webhook firing with the status of `VERIFICATION_STATUS_PROCESSING_COMPLETE`. For Document Income, the fee depends on the documents processed and which processing options are enabled (i.e. fraud, document parsing, or both). For bank statements, the fee is based on the number of pages in the statement; for all other document types, there is a flat fee per document. For Hosted Link, each session delivered via SMS or email will incur a one-time fee. There is no fee to use Hosted Link if you are not using Plaid to deliver sessions. When using Transfer, each Item initialized with Transfer (unless created using the [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) endpoint) will also incur the one-time Auth fee, and no additional fee will be incurred for using Auth endpoints with that Item. When using Layer, a billing event is incurred for each converted Link session (when `onSuccess` fires). You will not be billed for Layer eligibility checks or unconverted Layer sessions. ##### Subscription fee  Products that use subscription fee pricing are: * Transactions (except for the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint) * Recurring Transactions * Liabilities * Investments (except for the [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) endpoint) Under the subscription fee model, an Item will incur a monthly subscription fee as long as a valid `access_token` exists for the Item. Removing the Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) will end the subscription. The subscription will also be ended if the end user depermissions their Item, such as via [my.plaid.com](https://my.plaid.com/) or by contacting Plaid support. If the end user depermissions the Item via their financial institution's portal, this may also end the subscription, although this is not guaranteed, as not all institutions notify Plaid about permissions revocations performed via their portals. Once a subscription fee product has been added to an Item, it is not possible to end the subscription and leave the Item in place. The Item must be deleted, which can be done by calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . If the Item's subscription is active, Plaid will charge for the subscription even if no API calls are made for the Item or API calls cannot be successfully made for the Item (e.g. because the Item is in an error state). Plaid's subscription cycle is based on calendar months in the UTC time zone; each month begins a new cycle. Fees for Items created or removed in the middle of the month are not pro-rated. If you add a subscription-billed product to an Item while on a [Trial plan](https://plaid.com/docs/account/billing/index.html.md#trial-plans) (for example, by creating an Item initialized with Transactions, Investments, or Liabilities), upon upgrading to a paid plan, you will begin to be charged for that subscription. When using subscription fee products in Production, it is important to persist the access token so that you can remove the Item when needed to avoid being billed indefinitely. If you have created access tokens for which you are being billed but did not store the tokens, [contact support](https://dashboard.plaid.com/support) for assistance. A single Item can have multiple different subscriptions on it (for example, Transactions and Liabilities), but the same subscription will not be added multiple times to the same Item. Investments has two separate subscriptions that can be associated with an Item: Investments Holdings and Investments Transactions. Adding Investments to an Item via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) or by calling [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) adds the Investments Holdings subscription. Calling [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) on an Item adds both the Investments Transactions and Investments Holdings subscriptions. ##### Per-request flat fee  For per-request flat fee products, a flat fee is charged for each successful API call to that product endpoint. Products and endpoints that use per-request flat fee pricing are: * Balance ([/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) or [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) ) * Signal Transaction Scores ([/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) ) * Investments Move ([/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) ) * Transfer Signal or Balance fee ([/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) ), see [Transfer fee model](https://plaid.com/docs/account/billing/index.html.md#transfer-fee-model) for more details * Refresh endpoints, except for Statements Refresh ([/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) , [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) , [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) ) * Asset report PDF and Audit Copy ([/asset\_report/audit\_copy/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copycreate) , [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) ) * Identity Match ([/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) ), see below for more details * Beacon Account Insights ([/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) ) There is also a flat fee for each link delivered through SMS or email via Link Delivery (beta), when using Hosted Link with the optional Link Delivery feature enabled. Identity Match can optionally be enabled via the Dashboard. In this integration mode, the Identity Match check is automatically performed during Link and you never call the [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) endpoint directly. The billing trigger for Identity Match in this situation is when Plaid successfully obtains Identity data from the Item. If Plaid could not obtain any Identity data for the Item, you will not be billed. The [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) endpoint is a billable endpoint that is used by two different products, Balance and Signal Transaction Scores. It will be billed as a Balance API call if used with a Balance-only ruleset. It will be billed as a Signal Transaction Scores API call if used with a Signal Transaction Score-powered ruleset, or if used with no ruleset on a Signal Transaction Scores-enabled account. Calls to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) that use a ruleset (including the default ruleset) will be billed when the ruleset is evaluated, even if some or all data could not be extracted from the Item. ##### Per-request flexible fee  Products that use per-request flexible fee pricing are: * Assets * Statements Refresh * Enrich For per-request flexible fee products, a fee is charged for each successful API call to that product endpoint. The fee will vary depending on the amount of information requested in the API request. For Assets, the fee is calculated based on the number of Items in the report as well as the number of days of history requested. An additional fee is charged for an Asset Report containing more than 5 Items; this fee will be charged twice if the Asset Report contains more than 10 Items, and so on. An "Additional History" fee is also charged for each Item for which more than 61 days of history is requested. The Additional History fee is a flat fee regardless of how many days of additional history are requested; it does not matter how many days beyond 61 are requested. For Enrich, the flexible fee is based on the number of transactions sent to be enriched. For [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) , the flexible fee is based on the number of statements available between the provided start and end dates found when calling [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) . Note that you will be charged for any statement extracted, even those that you previously requested at an earlier date. ##### Per-Item flexible fee  Products that use per-Item flexible fee pricing are: * Statements (excluding [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) , which is charged as a per-request flexible fee) For per-Item flexible fee products, a fee is charged when the Item is created, which is deemed to occur when the `public_token` is created. The fee will vary depending on the amount of information requested when creating the Item. For Statements, the flexible fee is calculated based on the number of statements available within the date range requested when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . The fee will be charged even if you do not call any Statements endpoints. ##### Payment Initiation fee model  A fee is charged for each payment initiated. A payment is considered initiated if the end user reached the end of the payment flow and received a confirmation success screen. Standing orders (recurring payments) are considered a single payment but are billed on a separate pricing schedule from one-time payments. Fees will vary depending on the payment amount and the network used to transfer the payment. ##### Plaid Check fee model  Plaid Check (CRA) customers may be on bundle pricing or individual product pricing. If you are not sure which pricing model you are using, or to inquire about bundle pricing, contact your account manager. ###### Plaid Check bundle pricing  Plaid offers two Plaid Check (CRA) bundles: * **Plaid Income** — A suite of credit analytics to help lenders verify a user's income from their bank account. Includes Base Report and Income Insights. * **Plaid Underwriting** — A suite of credit analytics to help lenders assess risk and predict ability to pay. Includes Base Report, Cash Flow Insights, Network Insights, and LendScore. With bundle pricing, the first time a billable Check Report endpoint (any endpoint ending in `/get`, such as [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , [/cra/check\_report/cashflow\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcashflow_insightsget) , [/cra/check\_report/network\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportnetwork_insightsget) , [/cra/check\_report/lend\_score/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportlend_scoreget) , or [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) ) is called for a given `user_id` or `user_token`, you will be charged the bundle fee. You can then call any Plaid Check endpoints within that bundle for the same user identifier within a 24-hour window at no additional charge. After 24 hours, the user's report expires. Calls to product endpoints on an expired report will return a `CONSUMER_REPORT_EXPIRED` error. To continue calling product endpoints for that user, you must call [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) to generate a new Consumer Report. Once you create a new report and call a `/get` endpoint on it, you will be charged a new bundle fee, regardless of whether the original report has expired or not. If you are subscribed to multiple bundles and only use products that overlap between those bundles (for example, calling only [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) when subscribed to both Plaid Income and Plaid Underwriting), you will be charged the lower of the applicable bundle fees. ###### Plaid Check individual product pricing  With individual product pricing, most Plaid Check (CRA) products are charged when the corresponding `/get` endpoint is called ([/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , [/cra/check\_report/cashflow\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcashflow_insightsget) , [/cra/check\_report/network\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportnetwork_insightsget) , [/cra/check\_report/lend\_score/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportlend_scoreget) , and [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) ). The exception is Partner Insights, which is charged when the associated report is first generated and `partner_insights` is specified in the product array, which can happen during [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , or [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) . There is no additional charge to call an endpoint multiple times if the same Consumer Report (the data snapshot generated when a user goes through Link or when [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) is called) is being retrieved each time. However, if a new Consumer Report is generated for a given `user_id` or `user_token` by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , a new set of fees will be incurred when a `/get` endpoint is called on the new report. In addition to any product-specific charges, the first `/get` endpoint called for a given `user_id` or `user_token` and Consumer Report will also incur a Base Report charge. Note that [/cra/check\_report/network\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportnetwork_insightsget) is an exception: calling this endpoint does not trigger a Base Report charge. For example, if you call [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) followed by [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , you will be charged the Base Report fee when the first endpoint is called and only the Income Insights fee when the second is called. If you call the endpoints in the reverse order, both the Base Report fee and the Income Insights fee will be charged when [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) is called, and no fee will be charged when subsequently calling [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) . After 24 hours, the user's report expires. Calls to product endpoints on an expired report will return a `CONSUMER_REPORT_EXPIRED` error. To continue calling product endpoints for that user, you must call [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) to generate a new Consumer Report. Once you create a new report and call a `/get` endpoint on it, you will be charged a new fee, regardless of whether the original report has expired or not. When a new Consumer Report is created by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , a new set of fees will apply. The specific refresh fee incurred depends on which `/get` endpoint is called on the new report. For example, calling [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) after creating a new report incurs a Base Report Refresh fee; calling [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) incurs an Income Insights Refresh fee. ##### Transfer fee model  When working with Transfer, there are three primary fees: The Auth fee, the Signal fee, and the per-transfer fee. Existing contracts created or renewed prior to October 1, 2025 may contain references to a Transfer Risk Engine fee, which is assessed for each call to [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) . For all new Transfer contracts going forward, this fee has been replaced with the Signal fee (which may also be called the Signal Transaction Scores fee or Balance fee, depending on which product(s) you are using). ###### Auth fee  When using Transfer, each Item with the Transfer product (unless created by the [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) endpoint) will also have Auth added to the Item and will incur a one-time Auth fee in addition to the per-payment Transfer fee. ###### Signal fee  Calls to [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) or [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) will incur per-request flat fees for Balance or Signal Transaction Scores, depending on the ruleset invoked. A fee is incurred for every successful invocation of a ruleset. However, if the `authorization.decision` returned in the response is `user_action_required`, you will not be charged. ###### Per-transfer fee  A fee is charged for each transfer made. A transfer is considered made if it was successfully created. This occurs when [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) is successfully called, or if using Transfer UI instead of [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) , when the `onSuccess` callback is fired from the Link session where the transfer is authorized. The per-transfer fee is charged even if the payment is later reversed or clawed back. In such cases, a reversed payment fee may be charged as well. Fees will vary depending on the payment amount and the network used to make the payment. A per-transfer fee is also applied to funds transfers between your bank account and your balance held with Plaid, such as sweeps, or payments to and from the Plaid Ledger. ###### Operational fees  In addition to these product fees incurred by regular API activity, Transfer may charge operational fees for actions such as ACH returns, incoming wire transfers, and support requests for Plaid to perform certain actions such as providing a Written Statement of Unauthorized Debits (WSUD) or recalling or reversing a transfer. For more details, see [ACH Transfer Investigations](https://support.plaid.com/hc/en-us/articles/32881719199767-How-are-ACH-Transfer-Investigations-Escalated) or contact your account manager. ##### Monitor fee model  Monitor uses a model with two fees: * A base fee, which is incurred the first time a new user is scanned * A rescanning fee, which is incurred based on the number of users rescanned each month The rescanning fee is calculated based on the number of users on a rescanning program in a given month and works similarly to the subscription fee model. Plaid's subscription cycle is based on calendar months in the UTC time zone; each month begins a new cycle. Fees for users added to or removed from a rescanning program in the middle of the month are not pro-rated. To avoid being rebilled for a user you no longer need recurring scans for (e.g., a user who has closed their account with you), create a program specifically for former users, make sure rescans are disabled, and move the user into that program when they are offboarded from your system. ##### Identity Verification fee model  For Identity Verification, a fee is charged based on the end user performing certain activities during the Link flow. The following events are billed: * Anti-Fraud Engine (the first verification check run, typically when the end user enters their phone number to begin SMS verification. If this is skipped, the Anti-Fraud Engine fee will be incurred later on. For example, if the SMS check is skipped in favor of the document check, the document check will incur both the Anti-Fraud Engine fee and the document check fee.) * Data Source verification (cost varies based on the end user's country, see your pricing contract for details) * Document check * Selfie check If a retry is issued for a session, the retry will be billed like a new session, including the Anti-Fraud Engine and any other verification checks included in the retried session. #### Partnerships pricing  If you are using a Plaid partner, you will be charged for Plaid API usage performed by the partner using your processor token in the same way as if the calls had been made by you. The partner's API usage will not be included in your Plaid Dashboard [usage report](https://dashboard.plaid.com/activity/usage) . If you have questions about the partner's API activity, contact the Plaid partner. #### Viewing billable activity and invoices  To view billable activity for your account, see the Production [Usage](https://dashboard.plaid.com/activity/usage) page on the Dashboard. Invoices will be sent each month to the [billing contact](https://dashboard.plaid.com/settings/company/profile) configured for the team. #### Updating payment information  Pay as you go and Growth plan customers can update [payment method](https://dashboard.plaid.com/settings/team/billing) and [billing contact](https://dashboard.plaid.com/settings/company/profile) information on the Plaid Dashboard. Custom plan customers should contact their account manager to update this information. #### Updating products  To view your currently enabled products, see the [Products](https://dashboard.plaid.com/settings/team/products) page on the Dashboard under the Team Settings section. To add additional products to your Plaid account you can [submit the product request form](https://dashboard.plaid.com/overview/request-products) located on the Dashboard. This form is also accessible via the [Products](https://dashboard.plaid.com/settings/team/products) page. #### Viewing or changing pricing plans  To view current pricing or to switch between pricing plans, customers on Trial, Pay as you go, or Growth plans can use the [Plans page](https://dashboard.plaid.com/settings/team/plans) within the Dashboard. Customers with Trial or Pay as you go plans can upgrade their plan at any time. Customers with Growth plans can submit a request to upgrade or downgrade their plan at any time; requests will take effect after the minimum commitment period on the existing Growth plan has been satisfied. Customers on Custom plans should [contact support](https://dashboard.plaid.com/support/new/product-and-development) or their Plaid account manager. --- # Account - Overview | Plaid Docs Account Overview  ================= #### Learn about your Plaid developer account  #### Developer account overview  Your Plaid developer account is managed through the [Plaid Dashboard](https://dashboard.plaid.com) . (An image of "Plaid Dashboard with Institution Status, Usage, and Item Debugger options. Support shows recent case details and status.") This section provides information on topics related to managing your Plaid developer account, such as [billing](https://plaid.com/docs/account/billing/index.html.md) , [account security](https://plaid.com/docs/account/security/index.html.md) , and [team membership](https://plaid.com/docs/account/teams/index.html.md) . You can also find information on [logging and troubleshooting](https://plaid.com/docs/account/activity/index.html.md) in the dashboard, including institution status details and logs of API activity on your account. A Plaid developer account is different from a Plaid account at my.plaid.com. To manage the financial information you're sharing via Plaid, visit [my.plaid.com](https://my.plaid.com/) . --- # Account - For resellers | Plaid Docs Resellers  ========== #### Create and manage your customers  The Reseller Dashboard and API are functionality that Plaid has developed to support our authorized Reseller Partners. If you don't have a formal partnership established with Plaid, [contact us](https://plaid.com/contact/) to learn about signing up or to receive the appropriate contractual agreements to unlock this functionality. #### Overview  This guide explains how an authorized Plaid Reseller Partner can create and manage their End Customer teams. Each one of your End Customers is required to have a unique set of Plaid API keys, which enables reporting their billable usage, filing and managing support issues, customizing their Plaid Link experience, and registering their applications with our financial institution partners. #### Configuring your Reseller Partner team  When you join the Plaid Reseller Partner program, you will work with your partner account manager to set up a Reseller Partner team for your company. Get started by [signing up](https://dashboard.plaid.com/signup) for a Dashboard account, which will automatically create a team for you. Next, talk to your partner account manager to configure your team as a Reseller Partner team. If you already have a Plaid Dashboard account, or are using Plaid for a separate use case or business line, we require that you create a separate Reseller Partner team. You can use the same Dashboard user account (email address) to access both teams. #### Methods for creating and managing End Customers  Plaid offers two ways to create and manage End Customers: 1. The Dashboard (described in this guide) 2. The reseller API (documented in the [reseller API reference docs](https://plaid.com/docs/api/partner/index.html.md) ) The steps described in [Configuring your Reseller Partner team](https://plaid.com/docs/account/resellers/index.html.md#configuring-your-reseller-partner-team) are required regardless of whether you use the Dashboard or the reseller API. If you expect to onboard a large number of End Customers, or if you'd like to minimize the amount of manual work required by your operations staff, we strongly recommend that you integrate with our [reseller API](https://plaid.com/docs/api/partner/index.html.md) , which allows you to programmatically incorporate End Customer creation and management into your onboarding flows. Whether you create End Customers programmatically via the reseller API or manually in the Dashboard, they will be visible and active in both places. For example, if you create an End Customer via the API, you will be able to view it in the Dashboard, and vice versa. Under the hood, the reseller API and the Dashboard behave identically and follow the same onboarding process, which is described in [Creating End Customers](https://plaid.com/docs/account/resellers/index.html.md#creating-end-customers) . #### Viewing the Dashboard as a Reseller Partner  Being a member of a Reseller Partner team automatically grants you permission to create and manage End Customers. However, you must first switch to your Reseller Partner team in the Dashboard to exercise these permissions. Ensure that your Reseller Partner team's name appears in the top left-hand corner of the Dashboard. If a different team's name is displayed, click the team's name to open the team switcher and then select your Reseller Partner team's name: (An image of "Dropdown menu showing selected team 'My reseller team' and option to 'Create new team.'") If your Reseller Partner team does not appear in the list (which can happen if you have a lot of End Customers), you will first need to go to the Teams page. Click on your name in the bottom-left corner of any page and select [Teams](https://dashboard.plaid.com/personal/teams) . (An image of "Dropdown menu with options: Profile, Security, Teams, Logout; associated with user section labeled 'My Name'.") You can then access reseller partner features in the navigation bar on the left side of the dashboard (An image of "Manage End Customers: Options for Summary, Support, and Usage with icons for each.") #### Creating End Customers  First, follow the instructions in [Viewing the Dashboard as a Reseller Partner](https://plaid.com/docs/account/resellers/index.html.md#viewing-the-dashboard-as-a-reseller-partner) . Next, select the team switcher in top left-hand corner and then click **Create new team**. Fill out and submit the form. Plaid automatically enables new customers for Data Transparency Messaging, including all new End Customers. In Production, Link will not work if a use case has not been selected for Data Transparency Messaging. To automatically populate a Data Transparency Messaging use case, when filling out the form to create a new team, Select "Apply customization from your default Link configuration" in the Link Customization dropdown. This will duplicate the default Link customization from your parent account, including the use case for Data Transparency Messaging. Alternatively, you can individually customize this setting on the Dashboard on a per-End Customer basis by going to **[Link > Link Customization > Data Transparency](https://dashboard.plaid.com/link/data-transparency-v5)** . Once you have created the End Customer, it will appear in the [Partner End Customer Summary](https://dashboard.plaid.com/partner/customers-summary) page: (An image of "Partner End Customer Summary page with search, filter by Production and OAuth Status, create button, list of end customers.") You can view the newly created End Customer's API keys by clicking on the End Customer and navigating to the Developers > [Keys](https://dashboard.plaid.com/developers/keys) tab. The customer will automatically be enabled in Sandbox to facilitate testing. The newly created End Customer will be assigned a _status_, which will change as they move through the onboarding process. The possible statuses are described below: * `UNDER REVIEW`: You successfully created the End Customer, but more information is needed before Plaid can approve or deny them. This status is most commonly seen when the newly created End Customer is already a Plaid customer, in which case you will need to talk with your partner account manager to resolve the channel conflict. * `DENIED`: You successfully created the End Customer, but Plaid has determined that we cannot service them through your reseller contract. This status is most commonly seen in the case of channel conflicts (i.e., Plaid already has a contract with this End Customer). * `PENDING ENABLEMENT`: You successfully created the End Customer and Plaid has approved them. You may now enable the End Customer (see the next section, [Enabling End Customers](https://plaid.com/docs/account/resellers/index.html.md#enabling-end-customers) , for details on the enablement process). * `ACTIVE`: You successfully created and enabled the End Customer. The End Customer's API keys can now be used in the Production environment. #### Enabling End Customers  When you create an End Customer, they will be enabled in Sandbox. This allows you to test your End Customers prior to enabling them for full Production access. It also prevents you from accidentally incurring billable activity prior to launching with your End Customers. To enable an End Customer, find the end customer you wish to enable in the [Partner End Customer Summary](https://dashboard.plaid.com/partner/customers-summary) page, and then click the **Enable** button. Alternatively, you can select their team to navigate to the [Overview](https://dashboard.plaid.com/overview) page and then click **Get production access**. Enablement happens instantly. Once the End Customer has been enabled for full Production, you will be able to make API calls to Plaid in the full Production environment. Any remaining unused credits for free API calls will _not_ carry over into full Production. When you enable an End Customer, Plaid will automatically begin registering them with financial institutions that require OAuth access for connectivity, such as Chase and Capital One. Registration at most institutions happens within 24 hours, but for some institutions it may take several weeks. You can check the registration status for all OAuth institutions via the [OAuth institutions](https://dashboard.plaid.com/settings/compliance/us-oauth-institutions) page for a given End Customer. Alternatively, you can set up a webhook in the dashboard to get automatically notified when an End Customer has their OAuth status updated. To configure the webhook, go to the [webhooks page](https://dashboard.plaid.com/developers/webhooks) and create a new webhook listening to the **End Customer OAuth status updated** event type. For details on the webhook, see the [partner API documentation](https://plaid.com/docs/api/partner/index.html.md#partner_end_customer_oauth_status_updated) . If you encounter errors during OAuth registration, or if after 3 business days your end customer has not been registered at _any_ OAuth institutions, contact your partner account manager for help. #### Managing End Customers  All of your end customers' support tickets are searchable in the [Partner End Customer Support](https://dashboard.plaid.com/partner/customers-support) page, and their API usage data can be found in the [Partner End Customer Usage](https://dashboard.plaid.com/partner/customers-usage) page. #### Deleting End Customers  In some cases you may wish to delete an End Customer prior to enabling them for Production, possibly because they were created in error or because they are no longer working with you. To delete an End Customer, go to the [Partner End Customer Summary](https://dashboard.plaid.com/partner/customers-summary) page, and then click **Delete**: (An image of "Deleting an End Customer confirmation with Yes and No options. Lists End Customer 0-2, dates, status, and actions.") Deleting the End Customer will immediately deactivate their API keys and remove them from view in the Dashboard. This feature does not work for Production-enabled End Customers (those with a status of `ACTIVE`). To delete a Production-enabled customer, contact your partner account manager. --- # Account - Security | Plaid Docs Plaid Dashboard account security and account management  ======================================================== #### Learn how to protect and manage your Plaid Dashboard account  #### Password resets  To reset your password, log in to the Plaid Dashboard, then access the [Personal Security page](https://dashboard.plaid.com/personal/security) , which contains a password reset screen. If you ever forget your password to your Plaid Dashboard account, use the **Password reset** button on the login page to reset your password. You will only be able to receive your password reset email if you have verified your Plaid email address. If your email address is unverified, search your email for a message from [no-reply@plaid.com](https://plaid.commailto:no-reply@plaid.com) with the subject line "Confirm your email" and click on the link in that email to verify your address. You should then be able to reset your password. #### Two-factor authentication  Plaid allows you to enable two-factor authentication for your dashboard account via either text message or app-based authentication. After you enable two-factor authentication, you'll be prompted to enter an authentication code each time you sign in. When you enable two-factor authentication, Plaid will show you a backup recovery code. Be sure to write down the recovery code and store it in a safe place, since it will only be displayed once. To check whether your team members have enabled two-factor authentication, you can visit the [Team Members page](https://dashboard.plaid.com/settings/team/members) , where your team members' status will be displayed as "2FA ON", "2FA OFF", or "PENDING". #### SSO login  Plaid offers SSO (single sign-on) login to the Plaid Dashboard for all customers, except those on Pay-as-you-go-plans. We support all major identity providers, including Okta, Google Workspaces, OneLogin, and over 30 others. You can enable your account for SSO via the Dashboard, under [Settings > Team Settings > SSO](https://dashboard.plaid.com/settings/team/sso) . There is no additional charge for SSO enablement. SCIM support is available to customers on Premium Support packages. To learn more, contact your account manager. #### Rotating keys  If your `secret` is ever compromised, you should rotate it from the [Keys](https://dashboard.plaid.com/developers/keys) section of the Dashboard. Clicking the **Rotate secret** button will generate a new secret, which you can then copy and test. The old secret will still remain active until you delete it by clicking the **Delete** button. #### Managing notification settings  To control which emails you receive from Plaid, you can update your [notification settings](https://dashboard.plaid.com/settings/team/notification-preferences) in the Dashboard. #### Deleting accounts  To leave or delete a team, see [Leaving or deleting a team](https://plaid.com/docs/account/teams/index.html.md#leaving-or-deleting-a-team) . To delete your Plaid Dashboard login itself, [contact support](https://dashboard.plaid.com/support/new/product-and-development/account-administration/delete-account) . Note that deleting your login is irreversible. A Plaid Dashboard account is different from a Plaid account at my.plaid.com. To manage the financial information you're sharing via Plaid, visit [my.plaid.com](https://my.plaid.com/) . --- # Account - Teams | Plaid Docs Plaid teams  ============ #### Learn about Plaid teams  Your Plaid Dashboard account can create or join multiple teams to enable collaboration across different teams or companies. You can be a member of multiple Plaid teams, each with their own API keys and billing information. #### Creating a team  At the top-left of your Plaid Dashboard, click the team name drop-down and select **Create new team**. (An image of "Dropdown displaying team options: WonderWallet, WonderWallet Team 2, WizardCash, and option to create a new team.") Once you have submitted your team name and purpose into the form, click **Create team**. Your new team will come with a fresh set of API keys which can be used to build a new Plaid integration. #### Managing your team membership  You can create a new team, view your existing teams, and leave a team from the [Personal menu](https://dashboard.plaid.com/personal/teams) , found at the bottom-left of your Plaid Dashboard: (An image of "Personal menu with options: Profile, Security, Teams, Logout for Plaid User; dropdown indicator present.") #### Team-specific settings  Visit [Settings > Team Settings](https://dashboard.plaid.com/settings/company/profile) in your Plaid Dashboard to view your company information, team members, billing settings, and invoices: (An image of "Company and team settings menu with options for profile, branding, members, products, communication, link migrations, and compliance.") #### Team domains  In addition to manually adding and removing team members, which you can do from [Team settings](https://dashboard.plaid.com/settings/company/profile) , you can use the [Domains](https://dashboard.plaid.com/settings/team/domains) feature to automatically add new Plaid users to your team when they sign up with a verified email domain. This simplifies team management by preventing you from having to manually add members and also ensures that your co-workers join the correct Plaid team. To associate a domain with your team, go to the [Domains](https://dashboard.plaid.com/settings/team/domains) tab and go through the WorkOS flow to verify your domain. You must own and control your own domain name to use this feature; public email domains such as gmail.com are not eligible for domain verification. (An image of "no description available") Once domain verification is complete, which can take up to 48 hours, you can enable Domain Capture for that team by returning to the [Domains](https://dashboard.plaid.com/settings/team/domains) tab and clicking the "Enable" button for that team. When Domain Capture is enabled, Dashboard users who sign up with an email address matching your team's verified domain will be prompted to join after verifying their email. (An image of "no description available") You will receive an email notification whenever a user joins your team in this way. New members will be added with the "Default" permissions set. To accommodate different organizational structures, multiple teams may be associated with a single domain, and a single team may be associated with multiple domains. If a single domain is associated with multiple different teams, and Domain Capture is enabled for more than one of those teams, the user will be shown all eligible teams and prompted to choose which team(s) to join. Enabling Domain Capture is a reversible operation; you may disable Domain Capture at any time from the Domains tab. Managing Domain Verification and Domain Capture requires the Domain Verification permission, which is separate from the Team Management permission. #### Managing team member permissions  From the Team Settings menu, you can also add and remove team members, as long as you have the Team management permission. You can assign specific permissions to each team member that you add to your Plaid team. Members with the **Admin** permission are automatically granted all permissions to the entire Plaid Dashboard. Members with the **Team Management** permission have similar access to the Admin permission – they can see and manage almost everything. However, they can't view or change API keys or view and file support tickets. Some of what this role can do: * Make production / product requests * Change API configurations (OAuth redirect URIs, change pinned API version) * Configure webhooks * Configure team's display settings and name * Manage billing / invoices * Manage team membership * Manage OAuth migrations * Delete the team Members with the **Support** permission have access to the Support pages for viewing and filing support tickets. Members with the **Link Customization Write Access** permission can create or edit Link customizations. Certain pages are accessible to all Dashboard team members, regardless of their permissions. These pages include: * Overview * Status * Logs * Usage * Analytics You can also use the Team Settings page to control which environments team members have access to. In order to view the team's `client_id`, team members must have access to at least one environment. ##### Identity Verification, Monitor, and Beacon permissions  Members with Admin or Team Management permissions are able to assign granular permissions for Plaid Identity Verification, Monitor, and Beacon. There are numerous permission settings, which allow you to define who should be able to view certain information (e.g. end user PII) and take various actions. These permissions can be assigned while adding a team member or editing permissions for existing team members in the [Team Settings](https://dashboard.plaid.com/settings/team/members) page. Note that 2FA will need to be enabled for a user to be able to access this data. ##### Transfer Dashboard permissions  See the [Transfer Dashboard documentation](https://plaid.com/docs/transfer/dashboard/index.html.md#dashboard-permissions) for details on Transfer-specific Dashboard permissions. ##### Credit Dashboard permissions  * **Credit Dashboard All Permissions** - Grants access to all Credit Dashboard features. * **Credit Dashboard Access** - Grants access to view Credit Dashboard * **Credit Dashboard Application Creation** - Grants ability to create hosted link URLs * **Credit Dashboard User Profile Access** - Grants access to view Credit Dashboard user profiles * **Credit Dashboard View PII** - Allows viewing of PII on Credit Dashboard #### Consolidating multiple accounts using teams  Teams prevent you from having to maintain multiple developer accounts. However, if you have already created multiple accounts, you can still consolidate them into a single account without having to create new keys or re-apply for access. To do so, follow these steps: 1. Select an account to be the new primary account that will contain all the teams. 2. From each account that you will be consolidating into the new primary account, invite the new primary account to the team. 3. From each account that you will be consolidating into the new primary account, create a new empty team. 4. From the new primary account, accept the invitations. 5. From each account that you will be consolidating into the new primary account, leave the old team. Your teams will now be consolidated under the new account. #### Leaving or deleting a team  To leave or delete a team, click on your name in the lower-left corner of the Dashboard and select **Teams** to access the [Teams page](https://dashboard.plaid.com/personal/teams) . Click on the **...** button on the right side of the team's listing. Select **Leave Team** or **Delete Team**. Deleting the team will remove access to the team for all users, and the API keys for team will be deactivated. You must have the Team Management permission to delete a team. You may only delete a team via the Dashboard if you are on a Pay-as-you-go plan. If you have a dedicated Plaid account manager, contact your account manager instead to request team deletion. --- # API - Accounts | Plaid Docs Accounts  ========= #### API reference for retrieving account information and seeing all possible account types and subtypes  \=\*=\*=\*= #### /accounts/get  #### Retrieve accounts  The [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint can be used to retrieve a list of accounts associated with any linked Item. Plaid will only return active bank accounts — that is, accounts that are not closed and are capable of carrying a balance. To return new accounts that were created after the user linked their Item, you can listen for the [NEW\_ACCOUNTS\_AVAILABLE](https://plaid.com/docs/api/items/index.html.md#new_accounts_available) webhook and then use Link's [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to request that the user share this new account with you. [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) is free to use and retrieves cached information, rather than extracting fresh information from the institution. The balance returned will reflect the balance at the time of the last successful Item update. If the Item is enabled for a regularly updating product, such as Transactions, Investments, or Liabilities, the balance will typically update about once a day, as long as the Item is healthy. If the Item is enabled only for products that do not frequently update, such as Auth or Identity, balance data may be much older. For realtime balance information, use the paid endpoints [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) or [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) instead. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. object An optional object to filter `/accounts/get` results. \[string\] An array of `account_ids` to retrieve for the Account. ```bash curl -X POST https://sandbox.plaid.com/accounts/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node const request: AccountsGetRequest = { access_token: ACCESS_TOKEN, }; try { const response = await plaidClient.accountsGet(request); const accounts = response.data.accounts; } catch (error) { // handle error } ``` ```python request = AccountsGetRequest(access_token=ACCESS_TOKEN) response = client.accounts_get(request) accounts = response['accounts'] ``` ```java AccountsGetRequest request = new AccountsGetRequest() .accessToken(ACCESS_TOKEN); Response response = client() .accountsGet(request) .execute(); List accounts = response.body().getAccounts(); ``` ```ruby request = Plaid::AccountsGetRequest.new({ access_token: ACCESS_TOKEN }) response = client.accounts_get(request) accounts = response.accounts ``` ```go accountsGetRequest := plaid.NewAccountsGetRequest(accessToken) accountsGetResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest( *accountsGetRequest, ).Execute() if err != nil { // handle error } accounts := accountsGetResp.GetAccounts() ``` #### Response fields  \[object\] An array of financial institution accounts associated with the Item. If `/accounts/balance/get` was called, each account will include real-time balance information. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "accounts": [ { "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "holder_category": "personal", "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" }, { "account_id": "6PdjjRP6LmugpBy5NgQvUqpRXMWxzktg3rwrk", "balances": { "available": null, "current": 23631.9805, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "6666", "name": "Plaid 401k", "official_name": null, "subtype": "401k", "type": "investment" }, { "account_id": "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58", "balances": { "available": null, "current": 65262, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "7777", "name": "Plaid Student Loan", "official_name": null, "subtype": "student", "type": "loan" } ], "item": { "available_products": [ "balance", "identity", "payment_initiation", "transactions" ], "billed_products": [ "assets", "auth" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_117650", "institution_name": "Royal Bank of Plaid", "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6", "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook", "auth_method": "INSTANT_AUTH" }, "request_id": "bkVE1BHWMAZ9Rnr" } ``` #### Account type schema  The schema below describes the various `types` and corresponding `subtypes` that Plaid recognizes and reports for financial institution accounts. For a mapping of supported types and subtypes to Plaid products, see the [Account type / product support matrix](https://plaid.com/docs/api/accounts/index.html.md#account-type--product-support-matrix) . #### Properties  string An account type holding cash, in which funds are deposited. string A cash management account, typically a cash account at a brokerage string Certificate of deposit account string Checking account string An Electronic Benefit Transfer (EBT) account, used by certain public assistance programs to distribute funds (US only) string Health Savings Account (US only) that can only hold cash string A checking account that is limited in its purpose or usage. Note that this account subtype is opt-in only, meaning it cannot be connected in Link unless it is present in the subtypes filter. string Money market account string PayPal depository account string Prepaid debit card string Savings account string A credit card type account. string Bank-issued credit card string PayPal-issued credit card string A loan type account. string Auto loan string Business loan string Commercial loan string Construction loan string Consumer loan string Home Equity Line of Credit (HELOC) string Pre-approved line of credit string General loan string Mortgage loan string Other loan type or unknown loan type string Pre-approved overdraft account, usually tied to a checking account string Student loan string An investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage`. string Tax-advantaged college savings and prepaid tuition 529 plans (US) string Employer-sponsored money-purchase 401(a) retirement plan (US) string Standard 401(k) retirement account (US) string 403(b) retirement savings account for non-profits and schools (US) string Tax-advantaged deferred-compensation 457(b) retirement plan for governments and non-profits (US) string Standard brokerage account string Individual Savings Account (ISA) that pays interest tax-free (UK) string Standard cryptocurrency exchange account string Tax-advantaged Coverdell Education Savings Account (ESA) (US) string First Home Savings Account (FHSA) (Canada) string Fixed annuity string Guaranteed Investment Certificate (Canada) string Tax-advantaged Health Reimbursement Arrangement (HRA) benefit plan (US) string Non-cash tax-advantaged medical Health Savings Account (HSA) (US) string Traditional Individual Retirement Account (IRA) (US) string Non-cash Individual Savings Account (ISA) (UK) string Keogh self-employed retirement plan (US) string Life Income Fund (LIF) retirement account (Canada) string Life insurance account string Pre-approved line of credit string Locked-in Retirement Account (LIRA) (Canada) string Locked-in Retirement Income Fund (LRIF) (Canada) string Locked-in Retirement Savings Plan (Canada) string Mutual fund account string A cryptocurrency wallet where the user controls the private key string A non-taxable brokerage account that is not covered by a more specific subtype string An account whose type could not be determined string An annuity account not covered by other subtypes string An insurance account not covered by other subtypes string Standard pension account string Prescribed Registered Retirement Income Fund (Canada) string Plan that gives employees share of company profits string Qualifying share account string Registered Disability Savings Plan (RSDP) (Canada) string Registered Education Savings Plan (Canada) string Retirement account not covered by other subtypes string Restricted Life Income Fund (RLIF) (Canada) string Roth IRA (US) string Employer-sponsored Roth 401(k) plan (US) string Roth 403(b) retirement savings account for non-profits and schools (US) string Roth 457(b) deferred-compensation retirement plan for governments and non-profits (US) string Roth version of a standard pension account string Roth version of a profit sharing plan string Roth version of the Thrift Savings Plan (US) string Registered Retirement Income Fund (RRIF) (Canada) string Registered Retirement Savings Plan (Canadian, similar to US 401(k)) string Salary Reduction Simplified Employee Pension Plan (SARSEP), discontinued retirement plan (US) string Simplified Employee Pension IRA (SEP IRA), retirement plan for small businesses and self-employed (US) string Savings Incentive Match Plan for Employees IRA, retirement plan for small businesses (US) string Self-Invested Personal Pension (SIPP) (UK) string Standard stock plan account string Tax-Free Savings Account (TFSA), a retirement plan similar to a Roth IRA (Canada) string Thrift Savings Plan, a retirement savings and investment plan for Federal employees and members of the uniformed services. string Account representing funds or assets held by a trustee for the benefit of a beneficiary. Includes both revocable and irrevocable trusts. string 'Uniform Gift to Minors Act' (brokerage account for minors, US) string 'Uniform Transfers to Minors Act' (brokerage account for minors, US) string Tax-deferred capital accumulation annuity contract string A payroll account. string Standard payroll account string Other or unknown account type. #### Account type / product support matrix  The chart below indicates which products can be used with which account types. Note that some products can only be used with certain subtypes: * Auth and Signal require a debitable `checking`, `savings`, or `cash management` account. * Liabilities does not support `loan` types other than `student` or `mortgage`. * Transactions does not support `loan` types other than `student` or `mortgage`. * Investments does not support `depository` types other than `cash management`. Also note that not all institutions support all products; for details on which products a given institution supports, use [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) or look up the institution on the [Plaid Dashboard status page](https://dashboard.plaid.com/activity/status) or the [Coverage Explorer](https://plaid.com/docs/institutions/index.html.md) . | Product | Depository | Credit | Investments | Loan | Other | | --- | --- | --- | --- | --- | --- | | [Balance](https://plaid.com/docs/balance/index.html.md) | | | \* | | | | [Transactions](https://plaid.com/docs/transactions/index.html.md) | | | | | | | [Identity](https://plaid.com/docs/identity/index.html.md) | | | | | | | [Assets](https://plaid.com/docs/assets/index.html.md) | | | | | | | [Consumer Reports by Plaid Check](https://plaid.com/docs/check/index.html.md) | | | | | | | [Investments](https://plaid.com/docs/investments/index.html.md) | | | | | | | [Investments Move](https://plaid.com/docs/investments/index.html.md) | | | | | | | [Liabilities](https://plaid.com/docs/liabilities/index.html.md) | | | | | | | [Auth](https://plaid.com/docs/auth/index.html.md) | | | | | | | [Transfer](https://plaid.com/docs/transfer/index.html.md) | | | | | | | [Income (Bank Income flow)](https://plaid.com/docs/income/index.html.md) | | | | | | | [Statements](https://plaid.com/docs/statements/index.html.md) | | | | | | | [Signal](https://plaid.com/docs/signal/index.html.md) | | | | | | | [Payment Initiation (UK and Europe)](https://plaid.com/docs/payment-initiation/index.html.md) | | | | | | | [Virtual Accounts (UK and Europe)](https://plaid.com/docs/payment-initiation/index.html.md) | | | | | | \* Investments holdings data is not priced intra-day. #### Currency code schema  The following currency codes are supported by Plaid. #### Properties  string Plaid supports all ISO 4217 currency codes. string List of unofficial currency codes string Cardano string Basic Attention Token string Bitcoin Cash string Binance Coin string Bitcoin string Bitcoin Gold string Bitcoin Satoshi Vision string Chinese Yuan (offshore) string Dash string Dogecoin string Ethereum Classic string Ethereum string Pence sterling, i.e. British penny string Lisk string Neo string OmiseGO string Qtum string Tether string Stellar Lumen string Monero string Ripple string Zcash string 0x #### Investment transaction types schema  Valid values for investment transaction types and subtypes. Note that transactions representing inflow of cash will appear as negative amounts, outflow of cash will appear as positive amounts. #### Properties  string Buying an investment string Assignment of short option holding string Inflow of assets into a tax-advantaged account string Purchase to open or increase a position string Purchase to close a short position string Purchase using proceeds from a cash dividend string Purchase using proceeds from a cash interest payment string Purchase using long-term capital gain cash proceeds string Purchase using short-term capital gain cash proceeds string Selling an investment string Outflow of assets from a tax-advantaged account string Exercise of an option or warrant contract string Sell to close or decrease an existing holding string Sell to open a short position string A cancellation of a pending transaction string Activity that modifies a cash position string Fees paid for account maintenance string Inflow of assets into a tax-advantaged account string Inflow of cash into an account string Inflow of cash from a dividend string Inflow of stock from a distribution string Inflow of cash from interest string Fees paid for legal charges or services string Long-term capital gain received as cash string Fees paid for investment management of a mutual fund or other pooled investment vehicle string Fees paid for maintaining margin debt string Inflow of cash from a non-qualified dividend string Taxes paid on behalf of the investor for non-residency in investment jurisdiction string Pending inflow of cash string Pending outflow of cash string Inflow of cash from a qualified dividend string Short-term capital gain received as cash string Taxes paid on behalf of the investor string Taxes withheld on behalf of the customer string Fees incurred for transfer of a holding or account string Fees related to administration of a trust account string Unqualified capital gain received as cash string Outflow of cash from an account string Fees on the account, e.g. commission, bookkeeping, options-related. string Fees paid for account maintenance string Increase or decrease in quantity of item string Inflow of cash from a dividend string Inflow of cash from interest string Inflow of cash from interest receivable string Long-term capital gain received as cash string Fees paid for legal charges or services string Fees paid for investment management of a mutual fund or other pooled investment vehicle string Fees paid for maintaining margin debt string Inflow of cash from a non-qualified dividend string Taxes paid on behalf of the investor for non-residency in investment jurisdiction string Inflow of cash from a qualified dividend string Repayment of loan principal string Short-term capital gain received as cash string Inflow of stock from a distribution string Taxes paid on behalf of the investor string Taxes withheld on behalf of the customer string Fees incurred for transfer of a holding or account string Fees related to administration of a trust account string Unqualified capital gain received as cash string Activity that modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer string Assignment of short option holding string Increase or decrease in quantity of item string Exercise of an option or warrant contract string Expiration of an option or warrant contract string Stock exchanged at a pre-defined ratio as part of a merger between companies string Request fiat or cryptocurrency to an address or email string Inflow or outflow of fiat or cryptocurrency to an address or email string Inflow of stock from spin-off transaction of an existing holding string Inflow of stock from a forward split of an existing holding string Trade of one cryptocurrency for another string Movement of assets into or out of an account --- # API - Consent | Plaid Docs Consent  ======== #### API reference for managing consent  | Endpoints | | | --- | --- | | [/consent/events/get](https://plaid.com/docs/api/consent/index.html.md#consenteventsget) | Retrieve consent events | | See also | | | --- | --- | | [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) | Retrieve an Item (includes Item consent details) | \=\*=\*=\*= #### /consent/events/get  #### List a historical log of item consent events  List a historical log of Item consent events. Consent logs are only available for events occurring on or after November 7, 2024. Extremely recent events (occurring within the past 12 hours) may not be available via this endpoint. Up to three years of consent logs will be available via the endpoint. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. ```bash curl -X POST https://sandbox.plaid.com/consent/events/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node const request: ConsentEventsGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.consentEventsGet(request); const consentEvents = response.data.consent_events; const status = response.data.status; } catch (error) { // handle error } ``` ```python request = ConsentEventsGetRequest(access_token=accessToken) response = client.consent_events_get(request) consent_events = response['consent_events'] status = response['status'] ``` ```java ConsentEventsGetRequest request = new ConsentEventsGetRequest() .accessToken(accessToken); Response response = client().consentEventsGet(request).execute(); ConsentEvent[] consentEvents = response.body().getConsentEvents(); Status status = response.body().getStatus(); ``` ```ruby request = Plaid::ConsentEventsGetRequest.new({ access_token: accessToken }) response = client.consent_events_get(request) consentEvents = response.consent_events status = response.status ``` ```go request := plaid.NewConsentEventsGetRequest(accessToken) resp, _, err := client.PlaidApi.ConsentEventsGet(ctx).ConsentEventsGetRequest(*request).Execute() if err != nil { // handle error } consentEvents := resp.GetConsentEvents() status := resp.GetStatus() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. \[object\] A list of consent events. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. string The date and time when the consent event occurred, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Format: `date-time` string A broad categorization of the consent event. Possible values: `CONSENT_GRANTED`, `CONSENT_REVOKED`, `CONSENT_UPDATED` string Codes describing the object of a consent event. Possible values: `USER_AGREEMENT`, `USE_CASES`, `DATA_SCOPES`, `ACCOUNT_SCOPES`, `REVOCATION` nullable, string Unique identifier for the institution associated with the Item. Field is `null` for Items created via Same Day Micro-deposits. nullable, string The full name of the institution associated with the Item. Field is `null` for Items created via Same Day Micro-deposits. string The entity that initiated collection of consent. Possible values: `PLAID`, `DATA_PROVIDER`, `CUSTOMER`, `END_USER` \[string\] A list of strings containing the full list of use cases the end user has consented to for the Item. See the [full list](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md#updating-link-customizations) of use cases. \[string\] A list of strings containing the full list of data scopes the end user has consented to for the Item. These correspond to consented products; see the [full mapping](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md#data-scopes-by-product) of data scopes and products. \[object\] An array containing the accounts associated with the Item for which authorizations are granted. string Plaid’s unique identifier for the account. Like all Plaid identifiers, the `account_id` is case sensitive. string The last 2-4 alphanumeric characters of an account's official account number string The name of the account, either assigned by the user or by the financial institution itself string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` Response Object ```json { "request_id": "m8MDnv9okwxFNBV", "consent_events": [ { "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr", "event_type": "CONSENT_GRANTED", "event_code": "USER_AGREEMENT", "institution_id": "ins_123456", "institution_name": "Platypus bank", "initiator": "END_USER", "created_at": "2019-02-15T15:51:39Z", "consented_use_cases": [], "consented_data_scopes": [], "consented_accounts": [] }, { "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr", "event_type": "CONSENT_GRANTED", "event_code": "USE_CASES", "institution_id": "ins_123456", "institution_name": "Platypus bank", "initiator": "END_USER", "created_at": "2019-02-15T15:52:39Z", "consented_use_cases": [ "Send and receive money", "Track and manage your finances" ], "consented_data_scopes": [], "consented_accounts": [] }, { "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr", "event_type": "CONSENT_GRANTED", "event_code": "DATA_SCOPES", "institution_id": "ins_123456", "institution_name": "Platypus bank", "initiator": "END_USER", "created_at": "2019-02-15T15:52:39Z", "consented_use_cases": [], "consented_data_scopes": [ "account_balance_info", "contact_info", "account_routing_number" ], "consented_accounts": [] }, { "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr", "event_type": "CONSENT_GRANTED", "event_code": "ACCOUNT_SCOPES", "institution_id": "ins_123456", "institution_name": "Platypus bank", "initiator": "END_USER", "created_at": "2019-02-15T15:53:39Z", "consented_use_cases": [], "consented_data_scopes": [], "consented_accounts": [ { "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo", "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "type": "depository", "subtype": "checking" } ] }, { "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr", "event_type": "CONSENT_REVOKED", "event_code": "REVOCATION", "institution_id": "ins_123456", "institution_name": "Platypus bank", "initiator": "END_USER", "created_at": "2020-02-20T15:53:39Z", "consented_use_cases": [], "consented_data_scopes": [], "consented_accounts": [] } ] } ``` --- # API - Overview | Plaid Docs API Reference  ============== #### Comprehensive reference for integrating with Plaid API endpoints  #### API endpoints and webhooks  For documentation on specific API endpoints and webhooks, use the navigation menu or search. #### API access  To gain access to the Plaid API, create an account on the [Plaid Dashboard](https://dashboard.plaid.com) . Once you've completed the signup process and acknowledged our terms, we'll provide a live `client_id` and `secret` via the Dashboard. #### API protocols and headers  The Plaid API is JSON over HTTP. Requests are POST requests, and responses are JSON, with errors indicated in response bodies as `error_code` and `error_type` (use these in preference to HTTP status codes for identifying application-level errors). All responses come as standard JSON, with a small subset returning binary data where appropriate. The Plaid API is served over HTTPS TLS v1.2 to ensure data privacy; HTTP and HTTPS with TLS versions other than 1.2 are not supported. Clients must use an up to date root certificate bundle as the only TLS verification path; certificate pinning should never be used. All requests must include a `Content-Type` of `application/json` and the body must be valid JSON. Almost all Plaid API endpoints require a `client_id` and `secret`. These may be sent either in the request body or in the headers `PLAID-CLIENT-ID` and `PLAID-SECRET`. Every Plaid API response includes a `request_id`, either in the body or (in the case of endpoints that return binary data, such as [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) ) in the response headers. For faster support, include the `request_id` when contacting support regarding a specific API call. #### API host  ```switcher https://sandbox.plaid.com (Sandbox) https://production.plaid.com (Production) ``` Plaid has two environments: Sandbox and Production. Items cannot be moved between environments. The Sandbox environment supports only test Items. You can [request Production API access](https://dashboard.plaid.com/overview/production) via the Dashboard. #### API status and incidents  API status is available at [status.plaid.com](https://status.plaid.com) . API status and incidents are also available programmatically via the following endpoints: * [https://status.plaid.com/api/v2/status.json](https://status.plaid.com/api/v2/status.json) for current status * [https://status.plaid.com/api/v2/incidents.json](https://status.plaid.com/api/v2/incidents.json) for current and historical incidents For a complete list of all API status information available programmatically, as well as more information on using these endpoints, see the [Incident.io Status API documentation](https://docs.incident.io/status-pages/api) . For information on institution-specific status, see [Troubleshooting institution status](https://plaid.com/docs/account/activity/index.html.md#troubleshooting-institution-status) . #### Storing API data  Any token returned by the API is sensitive and should be stored securely. Except for the `public_token` and `link_token`, all Plaid tokens are long-lasting and should never be exposed on the client side. Consumer data obtained from the Plaid API is sensitive information and should be managed accordingly. For guidance and best practices on how to store and handle sensitive data, see the [Open Finance Security Data Standard](https://ofdss.org/#documents) . Identifiers used by the Plaid API that do not contain consumer data and are not keys or tokens are designed for usage in less sensitive contexts. The most common of these identifiers are the `account_id`, `item_id`, `link_session_id`, and `request_id`. These identifiers are commonly used for logging and debugging purposes. #### API field formats  ##### Strings  Many string fields returned by Plaid APIs are reported exactly as returned by the financial institution. For this reason, Plaid does not have maximum length limits or standardized formats for strings returned by the API. In practice, field lengths of 280 characters will generally be adequate for storing returned strings, although Plaid does not guarantee this as a maximum string length. ##### Numbers and money  Plaid returns all currency values as decimal values in dollars (or the equivalent for the currency being used), rather than as integers. In some cases, it may be possible for a money value returned by the Plaid API to have more than two digits of precision -- this is common, for example, when reporting crypto balances. #### OpenAPI definition file  OpenAPI is a standard format for describing RESTful APIs that allows those APIs to be integrated with tools for a wide variety of applications, including testing, client library generation, IDE integration, and more. The Plaid API is specified in our [Plaid OpenAPI GitHub repo](https://github.com/plaid/plaid-openapi) . #### Postman collection  The [Postman collection](https://github.com/plaid/plaid-postman) is a convenient tool for exploring Plaid API endpoints without writing code. The Postman collection provides pre-formatted requests for almost all of Plaid's API endpoints. All you have to do is fill in your API keys and any arguments. To get started, check out the [Plaid Postman Collection Quickstart](https://github.com/plaid/plaid-postman) on GitHub. #### Client libraries  See the [client libraries](https://plaid.com/docs/api/libraries/index.html.md) page for more information on Plaid's client libraries. --- # API - Institutions | Plaid Docs Institutions endpoints  ======================= #### Fetch data about supported institutions  #### Institution coverage  For a user-friendly overview of which institutions Plaid supports, and the product coverage at each institution, see the [US and Canada Coverage Explorer](https://plaid.com/docs/institutions/index.html.md) or [European Coverage Explorer](https://plaid.com/docs/institutions/europe/index.html.md) . The [status dashboard](https://dashboard.plaid.com/activity/status) also provides a browsable view of institutions and supported products, with a focus on reporting institution health and downtimes. For more detailed institution information, or to access this data programmatically, use the API endpoints described on this page. ##### Supported countries  For a list of which products are supported for each country, see [supported products by country](https://support.plaid.com/hc/en-us/articles/27895826947735-What-Plaid-products-are-supported-in-each-country-and-region) or the docs for the specific product you are interested in. By default, customers in the United States and Canada receive access to institutions in all countries in Sandbox, and to United States and Canada in Production. To gain access to additional countries in Production, [file a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . | Endpoints | | | --- | --- | | [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) | Get a list of all supported institutions meeting specified criteria | | [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) | Get details about a specific institution | | [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) | Look up an institution by name | The interface for these endpoints has changed in API version 2020-09-14. If you are using an older API version, see [API versioning](https://plaid.com/docs/api/versioning/index.html.md) . ### Endpoints  \=\*=\*=\*= #### /institutions/get  #### Get details of all supported institutions  Returns a JSON response containing details on all financial institutions currently supported by Plaid. Because Plaid supports thousands of institutions, results are paginated. If there is no overlap between an institution’s enabled products and a client’s enabled products, then the institution will be filtered out from the response. As a result, the number of institutions returned may not match the count specified in the call. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, integer The total number of Institutions to return. Minimum: `1` Maximum: `500` required, integer The number of Institutions to skip. Minimum: `0` required, \[string\] Specify which country or countries to include institutions from, using the ISO-3166-1 alpha-2 country code standard. In API versions 2019-05-29 and earlier, the `country_codes` parameter is an optional parameter within the `options` object and will default to `[US]` if it is not supplied. Min items: `1` Possible values: `US`, `GB`, `ES`, `NL`, `FR`, `IE`, `CA`, `DE`, `IT`, `PL`, `DK`, `NO`, `SE`, `EE`, `LT`, `LV`, `PT`, `BE`, `AT`, `FI` object An optional object to filter `/institutions/get` results. \[string\] Filter the Institutions based on which products they support. Will only return institutions that support all listed products. When filtering based on `auth`, an institution must support Instant Auth to match the criterion. To filter for Signal Transaction Scores support, use `balance`. To filter for Transfer support, use `auth`. Min items: `1` Possible values: `assets`, `auth`, `balance`, `employment`, `identity`, `cra_base_report`, `cra_income_insights`, `cra_cashflow_insights`, `cra_lend_score`, `cra_network_insights`, `cra_partner_insights`, `income_verification`, `identity_verification`, `investments`, `liabilities`, `payment_initiation`, `standing_orders`, `transactions` \[string\] Specify an array of routing numbers to filter institutions. The response will only return institutions that match all of the routing numbers in the array. Routing number records used for this matching are generally comprehensive; however, failure to match a given routing number to an institution does not necessarily mean that the institution is unsupported by Plaid. Invalid routing numbers (numbers that are not 9 digits in length or do not have a valid checksum) will be filtered from the array before the response is processed. If all provided routing numbers are invalid, an `INVALID_REQUEST` error with the code of `INVALID_FIELD` will be returned. boolean Limit results to institutions with or without OAuth login flows. Note that institutions will have `oauth` set to `true` if some Items associated with that institution are required to use OAuth flows; institutions in a state of migration to OAuth will have the `oauth` attribute set to `true`. boolean When `true`, return the institution's homepage URL, logo and primary brand color. Not all institutions' logos are available. Note that Plaid does not own any of the logos shared by the API, and that by accessing or using these logos, you agree that you are doing so at your own risk and will, if necessary, obtain all required permissions from the appropriate rights holders and adhere to any applicable usage guidelines. Plaid disclaims all express or implied warranties with respect to the logos. boolean When `true`, returns metadata related to the Auth product indicating which auth methods are supported. Default: `false` boolean When `true`, returns metadata related to the Payment Initiation product indicating which payment configurations are supported. Default: `false` ```node // Pull institutions const request: InstitutionsGetRequest = { count: 10, offset: 0, country_codes: ['US'], }; try { const response = await plaidClient.institutionsGet(request); const institutions = response.data.institutions; } catch (error) { // Handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/institutions/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "count": Number, "offset": Number, "country_codes": Array }' ``` ```ruby request = Plaid::InstitutionsGetRequest.new( { count: count, offset: offset, country_codes: ["US"], options: { products: ["transactions"], } } ) response = client.institutions_get(request) institutions = response.institutions ``` ```java InstitutionsGetRequest request = new InstitutionsGetRequest() .count(count) .offset(offset) .countryCodes(Arrays.asList(CountryCode.US)); Response response = client() .institutionsGet(request) .execute(); List institutions = response.body().getInstitutions(); ``` ```python request = InstitutionsGetRequest( country_codes=[CountryCode('US')], count=count, offset=offset ) response = client.institutions_get(request) institutions = response['institutions'] ``` ```go request := plaid.NewInstitutionsGetRequest(count, offset, countryCodes) resp, _, err := client.PlaidApi.InstitutionsGet(ctx).InstitutionsGetRequest(*request).Execute() if err != nil { // handle error } ``` #### Response fields  \[object\] A list of Plaid institutions string Unique identifier for the institution. Note that the same institution may have multiple records, each with different institution IDs; for example, if the institution has migrated to OAuth, there may be separate `institution_id`s for the OAuth and non-OAuth versions of the institution. Institutions that operate in different countries or with multiple login portals may also have separate `institution_id`s for each country or portal. string The official name of the institution. \[string\] A list of the Plaid products supported by the institution. Note that only institutions that support Instant Auth will return `auth` in the product array; institutions that do not list `auth` may still support other Auth methods such as Instant Match or Automated Micro-deposit Verification. To identify institutions that support those methods, use the `auth_metadata` object. For more details, see [Full Auth coverage](https://plaid.com/docs/auth/coverage/index.html.md) . The `income_verification` product here indicates support for Bank Income. Note: For Signal Transaction Scores and Transfer, listed institutions may be incomplete or incorrect. Instead, use the following: `balance` support also indicates coverage of Signal Transaction Scores; `auth` support also indicates coverage of Transfer. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of the country codes supported by the institution. Possible values: `US`, `GB`, `ES`, `NL`, `FR`, `IE`, `CA`, `DE`, `IT`, `PL`, `DK`, `NO`, `SE`, `EE`, `LT`, `LV`, `PT`, `BE`, `AT`, `FI` nullable, string The URL for the institution's website nullable, string Hexadecimal representation of the primary color used by the institution. If Plaid does not have primary color data for the institution, this field will be a deterministically generated fallback color. nullable, string Base64 encoded representation of the institution's logo, returned as a base64 encoded 152x152 PNG. Not all institutions' logos are available. \[string\] A list of routing numbers known to be associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is generally comprehensive but is not guaranteed to be a complete list of routing numbers for an institution. \[string\] A partial list of DTC numbers associated with the institution. boolean Indicates that the institution has an OAuth login flow. This will be `true` if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections. nullable, object The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Liabilities updates, Auth requests, Balance requests, Identity requests, Investments requests, and Liabilities requests. A login attempt is conducted during the initial Item add in Link. If there is not enough traffic to accurately calculate an institution's status, Plaid will return null rather than potentially inaccurate data. Institution status is accessible in the Dashboard and via the API using the `/institutions/get_by_id` endpoint with the `options.include_status` option set to true. Note that institution status is not available in the Sandbox environment. nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, \[object\] Details of recent health incidents associated with the institution. string The start date of the incident, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2020-10-30T15:26:48Z"`. Format: `date-time` nullable, string The end date of the incident, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2020-10-30T15:26:48Z"`. Format: `date-time` string The title of the incident \[object\] Updates on the health incident. string The content of the update. string The status of the incident. Possible values: `INVESTIGATING`, `IDENTIFIED`, `SCHEDULED`, `RESOLVED`, `UNKNOWN` string The date when the update was published, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2020-10-30T15:26:48Z"`. Format: `date-time` nullable, object Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests. boolean Indicates whether the institution supports payments from a different country. boolean Indicates whether the institution supports SEPA Instant payments. object A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the institution. Example: `{"GBP": "10000"}` boolean Indicates whether the institution supports returning refund details when initiating a payment. nullable, object Metadata specifically related to valid Payment Initiation standing order configurations for the institution. boolean Indicates whether the institution supports closed-ended standing orders by providing an end date. boolean This is only applicable to `MONTHLY` standing orders. Indicates whether the institution supports negative integers (-1 to -5) for setting up a `MONTHLY` standing order relative to the end of the month. \[string\] A list of the valid standing order intervals supported by the institution. Possible values: `WEEKLY`, `MONTHLY` Min length: `1` boolean Indicates whether the institution supports payment consents. nullable, object Metadata that captures information about the Auth features of an institution. nullable, object Metadata specifically related to which auth methods an institution supports. boolean Indicates if instant auth is supported. boolean Indicates if instant match is supported. boolean Indicates if automated microdeposits are supported. boolean Indicates if instant microdeposits are supported. integer The total number of institutions available via this endpoint string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "institutions": [ { "country_codes": [ "US" ], "institution_id": "ins_1", "name": "Bank of America", "products": [ "assets", "auth", "balance", "transactions", "identity", "liabilities" ], "routing_numbers": [ "011000138", "011200365", "011400495" ], "dtc_numbers": [ "2236", "0955", "1367" ], "oauth": false } ], "request_id": "tbFyCEqkU774ZGG", "total": 11384 } ``` \=\*=\*=\*= #### /institutions/get\_by\_id  #### Get details of an institution  Returns a JSON response containing details on a specified financial institution currently supported by Plaid. Versioning note: API versions 2019-05-29 and earlier allow use of the `public_key` parameter instead of the `client_id` and `secret` to authenticate to this endpoint. The `public_key` has been deprecated; all customers are encouraged to use `client_id` and `secret` instead. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the institution to get details about Min length: `1` required, \[string\] Specify which country or countries to include institutions from, using the ISO-3166-1 alpha-2 country code standard. In API versions 2019-05-29 and earlier, the `country_codes` parameter is an optional parameter within the `options` object and will default to `[US]` if it is not supplied. Possible values: `US`, `GB`, `ES`, `NL`, `FR`, `IE`, `CA`, `DE`, `IT`, `PL`, `DK`, `NO`, `SE`, `EE`, `LT`, `LV`, `PT`, `BE`, `AT`, `FI` object Specifies optional parameters for `/institutions/get_by_id`. If provided, must not be `null`. boolean When `true`, return an institution's logo, brand color, and URL. When available, the bank's logo is returned as a base64 encoded 152x152 PNG, the brand color is in hexadecimal format. The default value is `false`. Note that Plaid does not own any of the logos shared by the API and that by accessing or using these logos, you agree that you are doing so at your own risk and will, if necessary, obtain all required permissions from the appropriate rights holders and adhere to any applicable usage guidelines. Plaid disclaims all express or implied warranties with respect to the logos. Default: `false` boolean If `true`, the response will include status information about the institution. Default value is `false`. Default: `false` boolean When `true`, returns metadata related to the Auth product indicating which auth methods are supported. Default: `false` boolean When `true`, returns metadata related to the Payment Initiation product indicating which payment configurations are supported. Default: `false` ```python request = InstitutionsGetByIdRequest( institution_id=INSTITUTION_ID, country_codes=['US'] ) response = client.institutions_get_by_id(request) ``` ```bash curl -X POST https://sandbox.plaid.com/institutions/get_by_id \ -H 'Content-Type: application/json' \ -d '{ "institution_id": "ins_109512", "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "country_codes": Array }' ``` ```ruby request = Plaid::InstitutionsGetByIdRequest.new( { institution_id: INSTITUTION_ID, country_codes: ["US"] } ) response = client.institutions_get_by_id(request) ``` ```go request := plaid.NewInstitutionsGetByIdRequest(institutionID, countryCodes) response, _, err := client.PlaidApi.InstitutionsGetById(ctx).InstitutionsGetByIdRequest(*request).Execute() if err != nil { // handle error } ``` ```java InstitutionsGetByIdRequest request = new InstitutionsGetByIdRequest() .institutionId(INSTITUTION_ID) .addCountryCodesItem(countryCodes); Response response = client() .institutionsGetById(request) .execute(); Institution institution = response.body().getInstitution(); ``` ```node const request: InstitutionsGetByIdRequest = { institution_id: institutionID, country_codes: ['US'], }; try { const response = await plaidClient.institutionsGetById(request); const institution = response.data.institution; } catch (error) { // Handle error } ``` #### Response fields  object Details relating to a specific financial institution string Unique identifier for the institution. Note that the same institution may have multiple records, each with different institution IDs; for example, if the institution has migrated to OAuth, there may be separate `institution_id`s for the OAuth and non-OAuth versions of the institution. Institutions that operate in different countries or with multiple login portals may also have separate `institution_id`s for each country or portal. string The official name of the institution. \[string\] A list of the Plaid products supported by the institution. Note that only institutions that support Instant Auth will return `auth` in the product array; institutions that do not list `auth` may still support other Auth methods such as Instant Match or Automated Micro-deposit Verification. To identify institutions that support those methods, use the `auth_metadata` object. For more details, see [Full Auth coverage](https://plaid.com/docs/auth/coverage/index.html.md) . The `income_verification` product here indicates support for Bank Income. Note: For Signal Transaction Scores and Transfer, listed institutions may be incomplete or incorrect. Instead, use the following: `balance` support also indicates coverage of Signal Transaction Scores; `auth` support also indicates coverage of Transfer. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of the country codes supported by the institution. Possible values: `US`, `GB`, `ES`, `NL`, `FR`, `IE`, `CA`, `DE`, `IT`, `PL`, `DK`, `NO`, `SE`, `EE`, `LT`, `LV`, `PT`, `BE`, `AT`, `FI` nullable, string The URL for the institution's website nullable, string Hexadecimal representation of the primary color used by the institution. If Plaid does not have primary color data for the institution, this field will be a deterministically generated fallback color. nullable, string Base64 encoded representation of the institution's logo, returned as a base64 encoded 152x152 PNG. Not all institutions' logos are available. \[string\] A list of routing numbers known to be associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is generally comprehensive but is not guaranteed to be a complete list of routing numbers for an institution. \[string\] A partial list of DTC numbers associated with the institution. boolean Indicates that the institution has an OAuth login flow. This will be `true` if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections. nullable, object The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Liabilities updates, Auth requests, Balance requests, Identity requests, Investments requests, and Liabilities requests. A login attempt is conducted during the initial Item add in Link. If there is not enough traffic to accurately calculate an institution's status, Plaid will return null rather than potentially inaccurate data. Institution status is accessible in the Dashboard and via the API using the `/institutions/get_by_id` endpoint with the `options.include_status` option set to true. Note that institution status is not available in the Sandbox environment. nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, \[object\] Details of recent health incidents associated with the institution. string The start date of the incident, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2020-10-30T15:26:48Z"`. Format: `date-time` nullable, string The end date of the incident, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2020-10-30T15:26:48Z"`. Format: `date-time` string The title of the incident \[object\] Updates on the health incident. string The content of the update. string The status of the incident. Possible values: `INVESTIGATING`, `IDENTIFIED`, `SCHEDULED`, `RESOLVED`, `UNKNOWN` string The date when the update was published, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2020-10-30T15:26:48Z"`. Format: `date-time` nullable, object Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests. boolean Indicates whether the institution supports payments from a different country. boolean Indicates whether the institution supports SEPA Instant payments. object A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the institution. Example: `{"GBP": "10000"}` boolean Indicates whether the institution supports returning refund details when initiating a payment. nullable, object Metadata specifically related to valid Payment Initiation standing order configurations for the institution. boolean Indicates whether the institution supports closed-ended standing orders by providing an end date. boolean This is only applicable to `MONTHLY` standing orders. Indicates whether the institution supports negative integers (-1 to -5) for setting up a `MONTHLY` standing order relative to the end of the month. \[string\] A list of the valid standing order intervals supported by the institution. Possible values: `WEEKLY`, `MONTHLY` Min length: `1` boolean Indicates whether the institution supports payment consents. nullable, object Metadata that captures information about the Auth features of an institution. nullable, object Metadata specifically related to which auth methods an institution supports. boolean Indicates if instant auth is supported. boolean Indicates if instant match is supported. boolean Indicates if automated microdeposits are supported. boolean Indicates if instant microdeposits are supported. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "institution": { "country_codes": [ "US" ], "institution_id": "ins_109512", "name": "Houndstooth Bank", "products": [ "auth", "balance", "identity", "transactions" ], "routing_numbers": [ "011000138", "011200365", "011400495" ], "dtc_numbers": [ "2236", "0955", "1367" ], "oauth": false, "status": { "item_logins": { "status": "HEALTHY", "last_status_change": "2019-02-15T15:53:00Z", "breakdown": { "success": 0.9, "error_plaid": 0.01, "error_institution": 0.09 } }, "transactions_updates": { "status": "HEALTHY", "last_status_change": "2019-02-12T08:22:00Z", "breakdown": { "success": 0.95, "error_plaid": 0.02, "error_institution": 0.03, "refresh_interval": "NORMAL" } }, "auth": { "status": "HEALTHY", "last_status_change": "2019-02-15T15:53:00Z", "breakdown": { "success": 0.91, "error_plaid": 0.01, "error_institution": 0.08 } }, "identity": { "status": "DEGRADED", "last_status_change": "2019-02-15T15:50:00Z", "breakdown": { "success": 0.42, "error_plaid": 0.08, "error_institution": 0.5 } }, "investments": { "status": "HEALTHY", "last_status_change": "2019-02-15T15:53:00Z", "breakdown": { "success": 0.89, "error_plaid": 0.02, "error_institution": 0.09 }, "liabilities": { "status": "HEALTHY", "last_status_change": "2019-02-15T15:53:00Z", "breakdown": { "success": 0.89, "error_plaid": 0.02, "error_institution": 0.09 } } }, "investments_updates": { "status": "HEALTHY", "last_status_change": "2019-02-12T08:22:00Z", "breakdown": { "success": 0.95, "error_plaid": 0.02, "error_institution": 0.03, "refresh_interval": "NORMAL" } }, "liabilities_updates": { "status": "HEALTHY", "last_status_change": "2019-02-12T08:22:00Z", "breakdown": { "success": 0.95, "error_plaid": 0.02, "error_institution": 0.03, "refresh_interval": "NORMAL" } } }, "primary_color": "#004966", "url": "https://plaid.com", "logo": null }, "request_id": "m8MDnv9okwxFNBV" } ``` \=\*=\*=\*= #### /institutions/search  #### Search institutions  Returns a JSON response containing details for institutions that match the query parameters, up to a maximum of ten institutions per query. Versioning note: API versions 2019-05-29 and earlier allow use of the `public_key` parameter instead of the `client_id` and `secret` parameters to authenticate to this endpoint. The `public_key` parameter has since been deprecated; all customers are encouraged to use `client_id` and `secret` instead. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The search query. Institutions with names matching the query are returned Min length: `1` \[string\] Filter the Institutions based on whether they support all products listed in `products`. Provide `null` to get institutions regardless of supported products. Note that when `auth` is specified as a product, if you are enabled for Instant Match or Automated Micro-deposits, institutions that support those products will be returned even if `auth` is not present in their product array. To search for Transfer support, use `auth`; to search for Signal Transaction Scores support, use `balance`. Min items: `1` Possible values: `assets`, `auth`, `balance`, `employment`, `identity`, `income_verification`, `investments`, `liabilities`, `identity_verification`, `payment_initiation`, `standing_orders`, `statements`, `transactions` required, \[string\] Specify which country or countries to include institutions from, using the ISO-3166-1 alpha-2 country code standard. In API versions 2019-05-29 and earlier, the `country_codes` parameter is an optional parameter within the `options` object and will default to `[US]` if it is not supplied. Possible values: `US`, `GB`, `ES`, `NL`, `FR`, `IE`, `CA`, `DE`, `IT`, `PL`, `DK`, `NO`, `SE`, `EE`, `LT`, `LV`, `PT`, `BE`, `AT`, `FI` object An optional object to filter `/institutions/search` results. boolean Limit results to institutions with or without OAuth login flows. Note that institutions will have `oauth` set to `true` if some Items associated with that institution are required to use OAuth flows; institutions in a state of migration to OAuth will have the `oauth` attribute set to `true`. boolean When true, return the institution's homepage URL, logo and primary brand color. boolean When `true`, returns metadata related to the Auth product indicating which auth methods are supported. Default: `false` boolean When `true`, returns metadata related to the Payment Initiation product indicating which payment configurations are supported. Default: `false` object Additional options that will be used to filter institutions by various Payment Initiation configurations. string A unique ID identifying the payment string A unique ID identifying the payment consent ```node const request: InstitutionsSearchRequest = { query: institutionID, products: ['transactions'], country_codes: ['US'], }; try { const response = await plaidClient.institutionsSearch(request); const institutions = response.data.institutions; } catch (error) { // Handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/institutions/search \ -H 'Content-Type: application/json' \ -d '{ "query": "Gingham", "products": ["transactions"], "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "country_codes": ["US"] }' ``` ```ruby # search with products request = Plaid::InstitutionsSearchRequest.new( { query: SEARCH_QUERY, products: ["transactions"], country_codes: ["US"] } ) response = client.institutions_search(request) ``` ```java InstitutionsSearchRequest request = new InstitutionsSearchRequest() .countryCodes(Arrays.asList(CountryCode.US)) .products(Arrays.asList(Products.IDENTITY)) .query(SEARCH_QUERY); Response response = client() .institutionsSearch(request) .execute(); List results = response.body().getInstitutions(); ``` ```python request = InstitutionsSearchRequest( query=SEARCH_QUERY, products=[Products('transactions')], country_codes=[CountryCode('US')], ) response = client.institutions_search(request) ``` ```go request := plaid.NewInstitutionsSearchRequest(query, products, countryCodes) response, _, err := client.PlaidApi.InstitutionsSearch(ctx).InstitutionsSearchRequest(*request).Execute() if err != nil { // handle error } ``` #### Response fields  \[object\] An array of institutions matching the search criteria string Unique identifier for the institution. Note that the same institution may have multiple records, each with different institution IDs; for example, if the institution has migrated to OAuth, there may be separate `institution_id`s for the OAuth and non-OAuth versions of the institution. Institutions that operate in different countries or with multiple login portals may also have separate `institution_id`s for each country or portal. string The official name of the institution. \[string\] A list of the Plaid products supported by the institution. Note that only institutions that support Instant Auth will return `auth` in the product array; institutions that do not list `auth` may still support other Auth methods such as Instant Match or Automated Micro-deposit Verification. To identify institutions that support those methods, use the `auth_metadata` object. For more details, see [Full Auth coverage](https://plaid.com/docs/auth/coverage/index.html.md) . The `income_verification` product here indicates support for Bank Income. Note: For Signal Transaction Scores and Transfer, listed institutions may be incomplete or incorrect. Instead, use the following: `balance` support also indicates coverage of Signal Transaction Scores; `auth` support also indicates coverage of Transfer. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of the country codes supported by the institution. Possible values: `US`, `GB`, `ES`, `NL`, `FR`, `IE`, `CA`, `DE`, `IT`, `PL`, `DK`, `NO`, `SE`, `EE`, `LT`, `LV`, `PT`, `BE`, `AT`, `FI` nullable, string The URL for the institution's website nullable, string Hexadecimal representation of the primary color used by the institution. If Plaid does not have primary color data for the institution, this field will be a deterministically generated fallback color. nullable, string Base64 encoded representation of the institution's logo, returned as a base64 encoded 152x152 PNG. Not all institutions' logos are available. \[string\] A list of routing numbers known to be associated with the institution. This list is provided for the purpose of looking up institutions by routing number. It is generally comprehensive but is not guaranteed to be a complete list of routing numbers for an institution. \[string\] A partial list of DTC numbers associated with the institution. boolean Indicates that the institution has an OAuth login flow. This will be `true` if OAuth is supported for any Items associated with the institution, even if the institution also supports non-OAuth connections. nullable, object The status of an institution is determined by the health of its Item logins, Transactions updates, Investments updates, Liabilities updates, Auth requests, Balance requests, Identity requests, Investments requests, and Liabilities requests. A login attempt is conducted during the initial Item add in Link. If there is not enough traffic to accurately calculate an institution's status, Plaid will return null rather than potentially inaccurate data. Institution status is accessible in the Dashboard and via the API using the `/institutions/get_by_id` endpoint with the `options.include_status` option set to true. Note that institution status is not available in the Sandbox environment. nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, object A representation of the status health of a request type. Auth requests, Balance requests, Identity requests, Investments requests, Liabilities requests, Transactions updates, Investments updates, Liabilities updates, and Item logins each have their own status object. deprecated, string This field is deprecated in favor of the `breakdown` object, which provides more granular institution health data. `HEALTHY`: the majority of requests are successful `DEGRADED`: only some requests are successful `DOWN`: all requests are failing Possible values: `HEALTHY`, `DEGRADED`, `DOWN` string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) formatted timestamp of the last status change for the institution. Format: `date-time` object A detailed breakdown of the institution's performance for a request type. The values for `success`, `error_plaid`, and `error_institution` sum to 1. The time range used for calculating the breakdown may range from the most recent few minutes to the past six hours. In general, smaller institutions will show status that was calculated over a longer period of time. For Investment updates, which are refreshed less frequently, the period assessed may be 24 hours or more. For more details, see [Institution status details](https://plaid.com/docs/account/activity/index.html.md#institution-status-details) . number The percentage of login attempts that are successful, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an internal Plaid issue, expressed as a decimal. Format: `double` number The percentage of logins that are failing due to an issue in the institution's system, expressed as a decimal. Format: `double` string How frequently data for subscription products like Investments, Transactions, and Liabilities, is being refreshed, relative to the institution's normal scheduling. The `refresh_interval` may be `DELAYED` or `STOPPED` even when the success rate is high. Possible values: `NORMAL`, `DELAYED`, `STOPPED` nullable, \[object\] Details of recent health incidents associated with the institution. string The start date of the incident, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2020-10-30T15:26:48Z"`. Format: `date-time` nullable, string The end date of the incident, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2020-10-30T15:26:48Z"`. Format: `date-time` string The title of the incident \[object\] Updates on the health incident. string The content of the update. string The status of the incident. Possible values: `INVESTIGATING`, `IDENTIFIED`, `SCHEDULED`, `RESOLVED`, `UNKNOWN` string The date when the update was published, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2020-10-30T15:26:48Z"`. Format: `date-time` nullable, object Metadata that captures what specific payment configurations an institution supports when making Payment Initiation requests. boolean Indicates whether the institution supports payments from a different country. boolean Indicates whether the institution supports SEPA Instant payments. object A mapping of currency to maximum payment amount (denominated in the smallest unit of currency) supported by the institution. Example: `{"GBP": "10000"}` boolean Indicates whether the institution supports returning refund details when initiating a payment. nullable, object Metadata specifically related to valid Payment Initiation standing order configurations for the institution. boolean Indicates whether the institution supports closed-ended standing orders by providing an end date. boolean This is only applicable to `MONTHLY` standing orders. Indicates whether the institution supports negative integers (-1 to -5) for setting up a `MONTHLY` standing order relative to the end of the month. \[string\] A list of the valid standing order intervals supported by the institution. Possible values: `WEEKLY`, `MONTHLY` Min length: `1` boolean Indicates whether the institution supports payment consents. nullable, object Metadata that captures information about the Auth features of an institution. nullable, object Metadata specifically related to which auth methods an institution supports. boolean Indicates if instant auth is supported. boolean Indicates if instant match is supported. boolean Indicates if automated microdeposits are supported. boolean Indicates if instant microdeposits are supported. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "institutions": [ { "country_codes": [ "US" ], "institution_id": "ins_109513", "name": "Theoretical Bank", "oauth": true, "products": [ "assets", "auth", "balance", "cra_lend_score", "cra_plaid_credit_score", "identity", "identity_match", "income", "pay_by_bank", "processor_payments", "recurring_transactions", "transactions", "transfer" ], "routing_numbers": [ "031101270", "103100194", "103112357" ] } ], "request_id": "QheuqaazREmq9xp" } ``` ### Webhooks  Institution status alerts are configured within the [developer dashboard](https://dashboard.plaid.com/settings/team/notification-preferences) . In the dashboard, you can choose to receive alerts as either emails or webhooks. All dashboard-configured institution status alerts will have type `DASHBOARD_CONFIGURED_ALERT`. \=\*=\*=\*= #### INSTITUTION\_STATUS\_ALERT\_TRIGGERED  Fired when institution status meets the conditions configured in the developer dashboard. #### Properties  string `DASHBOARD_CONFIGURED_ALERT` string `INSTITUTION_STATUS_ALERT_TRIGGERED` string The ID of the associated institution. number The global success rate of the institution, calculated based on item add health. Format: `double` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "DASHBOARD_CONFIGURED_ALERT", "webhook_code": "INSTITUTION_STATUS_ALERT_TRIGGERED", "institution_id": "ins_3", "institution_overall_success_rate": 0.9, "environment": "production" } ``` --- # API - Items | Plaid Docs Items  ====== #### API reference for managing Items  | Endpoints | | | --- | --- | | [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) | Retrieve an Item | | [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) | Remove an Item | | [/item/webhook/update](https://plaid.com/docs/api/items/index.html.md#itemwebhookupdate) | Update a webhook URL | | [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) | Exchange a public token from Link for an access token | | [/item/access\_token/invalidate](https://plaid.com/docs/api/items/index.html.md#itemaccess_tokeninvalidate) | Rotate an access token without deleting the Item | | See also | | | --- | --- | | [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) | Create a test Item (Sandbox only) | | [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) | Force an Item into an error state (Sandbox only) | | [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) | Set Auth verification status (Sandbox only) | | [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) | Fire a test webhook (Sandbox only) | | Webhooks | | | --- | --- | | [ERROR](https://plaid.com/docs/api/items/index.html.md#error) | Item has entered an error state | | [LOGIN\_REPAIRED](https://plaid.com/docs/api/items/index.html.md#login_repaired) | Item has healed from `ITEM_LOGIN_REQUIRED` without update mode | | [NEW\_ACCOUNTS\_AVAILABLE](https://plaid.com/docs/api/items/index.html.md#new_accounts_available) | New account detected for an Item | | [PENDING\_DISCONNECT](https://plaid.com/docs/api/items/index.html.md#pending_disconnect) | Item access is about to expire (US/CA) or end | | [PENDING\_EXPIRATION](https://plaid.com/docs/api/items/index.html.md#pending_expiration) | Item access is about to expire (UK/EU) | | [USER\_PERMISSION\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) | The user has revoked access to an Item | | [USER\_ACCOUNT\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_account_revoked) | The user has revoked access to an account | | [WEBHOOK\_UPDATE\_ACKNOWLEDGED](https://plaid.com/docs/api/items/index.html.md#webhook_update_acknowledged) | Item webhook URL updated | ### Token exchange flow  Many API calls to Plaid product endpoints require an `access_token`. An `access_token` corresponds to an _Item_, which is a login at a financial institution. To obtain an `access_token`: 1. Obtain a `link_token` by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . 2. Initialize Link by passing in the `link_token`. When your user completes the Link flow, Link will pass back a `public_token` via the [onSuccess callback](https://plaid.com/docs/link/web/index.html.md#onsuccess) , or, if using [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) , via a webhook. For more information on initializing and receiving data back from Link, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . 3. Exchange the `public_token` for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . The `access_token` can then be used to call Plaid endpoints and obtain information about an Item. In addition to the primary flow, several other token flows exist. The [Link update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow allows you to update an `access_token` that has stopped working. The Sandbox testing environment also offers the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint, which allows you to create a `public_token` without using Link. The [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) and [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) flows provide the `public_token` via the backend rather than using the frontend `onSuccess` callback. ### Endpoints  \=\*=\*=\*= #### /item/get  #### Retrieve an Item  Returns information about the status of an Item. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. ```bash curl -X POST https://sandbox.plaid.com/item/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node const request: ItemGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.itemGet(request); const item = response.data.item; const status = response.data.status; } catch (error) { // handle error } ``` ```python request = ItemGetRequest(access_token=accessToken) response = client.item_get(request) item = response['item'] status = response['status'] ``` ```java ItemGetRequest request = new ItemGetRequest() .accessToken(accessToken); Response response = client().itemGet(request).execute(); Item item = response.body().getItem(); Status status = response.body().getStatus(); ``` ```ruby request = Plaid::ItemGetRequest.new({ access_token: accessToken }) response = client.item_get(request) item = response.item status = response.status ``` ```go request := plaid.NewItemGetRequest(accessToken) resp, _, err := client.PlaidApi.ItemGet(ctx).ItemGetRequest(*request).Execute() item := resp.GetItem() status := resp.GetStatus() ``` #### Response fields  object Metadata about the Item string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string The date and time when the Item was created, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` \[string\] A list of use cases that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . You can see the full list of use cases or update the list of use cases to request at any time via the Link Customization section of the [Plaid Dashboard](https://dashboard.plaid.com/link/data-transparency-v5) . \[string\] A list of data scopes that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . These are based on the `consented_products`; see the [full mapping](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md#data-scopes-by-product) of data scopes and products. Possible values: `account_balance_info`, `contact_info`, `account_routing_number`, `transactions`, `credit_loan_info`, `investments`, `payroll_info`, `income_verification_paystubs_info`, `income_verification_w2s_info`, `income_verification_bank_statements`, `income_verification_employment_info`, `bank_statements`, `risk_info`, `network_insights_lite`, `fraud_info` nullable, object Information about the last successful and failed transactions update for the Item. nullable, object Information about the last successful and failed investments update for the Item. nullable, string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) timestamp of the last successful investments update for the Item. The status will update each time Plaid successfully connects with the institution, regardless of whether any new data is available in the update. Format: `date-time` nullable, string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) timestamp of the last failed investments update for the Item. The status will update each time Plaid fails an attempt to connect with the institution, regardless of whether any new data is available in the update. Format: `date-time` nullable, object Information about the last successful and failed transactions update for the Item. nullable, string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) timestamp of the last successful transactions update for the Item. The status will update each time Plaid successfully connects with the institution, regardless of whether any new data is available in the update. This field does not reflect transactions updates performed by non-Transactions products (e.g. Signal). Format: `date-time` nullable, string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) timestamp of the last failed transactions update for the Item. The status will update each time Plaid fails an attempt to connect with the institution, regardless of whether any new data is available in the update. This field does not reflect transactions updates performed by non-Transactions products (e.g. Signal). Format: `date-time` nullable, object Information about the last webhook fired for the Item. nullable, string [ISO 8601](https://wikipedia.org/wiki/ISO_8601) timestamp of when the webhook was fired. Format: `date-time` string The last webhook code sent. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "item": { "created_at": "2019-01-22T04:32:00Z", "available_products": [ "balance", "auth" ], "billed_products": [ "identity", "transactions" ], "products": [ "identity", "transactions" ], "error": null, "institution_id": "ins_109508", "institution_name": "First Platypus Bank", "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr", "update_type": "background", "webhook": "https://plaid.com/example/hook", "auth_method": null, "consented_products": [ "identity", "transactions" ], "consented_data_scopes": [ "account_balance_info", "contact_info", "transactions" ], "consented_use_cases": [ "Verify your account", "Track and manage your finances" ], "consent_expiration_time": "2024-03-16T15:53:00Z" }, "status": { "transactions": { "last_successful_update": "2019-02-15T15:52:39Z", "last_failed_update": "2019-01-22T04:32:00Z" }, "last_webhook": { "sent_at": "2019-02-15T15:53:00Z", "code_sent": "DEFAULT_UPDATE" } }, "request_id": "m8MDnv9okwxFNBV" } ``` \=\*=\*=\*= #### /item/remove  #### Remove an Item  The [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) endpoint allows you to remove an Item. Once removed, the `access_token`, as well as any processor tokens or bank account tokens associated with the Item, is no longer valid and cannot be used to access any data that was associated with the Item. Calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) is a recommended best practice when offboarding users or if a user chooses to disconnect an account linked via Plaid. For subscription products, such as Transactions, Liabilities, and Investments, calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) is required to end subscription billing for the Item, unless the end user revoked permission (e.g. via [https://my.plaid.com/](https://my.plaid.com/) ). For more details, see [Subscription fee model](https://plaid.com/docs/account/billing/index.html.md#subscription-fee) . On a Trial plan, calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) does not impact the number of remaining Trial Items (bank connections) you have available. Removing an Item does not affect any Asset Reports or Audit Copies you have already created, which will remain accessible until you remove access to them specifically using the [/asset\_report/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportremove) endpoint. Also note that for certain OAuth-based institutions, an Item removed via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) may still show as an active connection in the institution's OAuth permission manager. API versions 2019-05-29 and earlier return a `removed` boolean as part of the response. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. string The reason for removing the item `FRAUD_FIRST_PARTY`: The end user who owns the connected bank account committed fraud `FRAUD_FALSE_IDENTITY`: The end user created the connection using false identity information or stolen credentials `FRAUD_ABUSE`: The end user is abusing the client's service or platform through their connected account `FRAUD_OTHER`: Other fraud-related reasons involving the end user not covered by the specific fraud categories `CONNECTION_IS_NON_FUNCTIONAL`: The connection to the end user's financial institution is broken and cannot be restored `OTHER`: Any other reason for removing the connection not covered by the above categories Possible values: `FRAUD_FIRST_PARTY`, `FRAUD_FALSE_IDENTITY`, `FRAUD_ABUSE`, `FRAUD_OTHER`, `CONNECTION_IS_NON_FUNCTIONAL`, `OTHER` string Additional context or details about the reason for removing the item. Personally identifiable information, such as an email address or phone number, should not be included in the `reason_note`. Max length: `512` ```bash curl -X POST https://sandbox.plaid.com/item/remove \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node const request: ItemRemoveRequest = { access_token: accessToken, }; try { const response = await plaidClient.itemRemove(request); // The Item was removed, access_token is now invalid } catch (error) { // handle error } // The Item was removed, access_token is now invalid ``` ```python request = ItemRemoveRequest(access_token=accessToken) response = client.item_remove(request) # The Item was removed and the access_token is now invalid ``` ```java ItemRemoveRequest request = new ItemRemoveRequest() .accessToken(accessToken); Response response = client() .itemRemove(request) .execute(); // The Item was removed and the access_token is now invalid ``` ```ruby request = Plaid::ItemRemoveRequest.new({ access_token: accessToken }) response = client.item_remove(request) # The Item was removed and the access_token is now invalid ``` ```go request := plaid.NewItemRemoveRequest(accessToken) _, _, err := client.PlaidApi.ItemRemove(ctx).ItemRemoveRequest(*request).Execute() // The Item was removed and the access_token is now invalid ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "m8MDnv9okwxFNBV" } ``` \=\*=\*=\*= #### /item/webhook/update  #### Update Webhook URL  The POST [/item/webhook/update](https://plaid.com/docs/api/items/index.html.md#itemwebhookupdate) allows you to update the webhook URL associated with an Item. This request triggers a [WEBHOOK\_UPDATE\_ACKNOWLEDGED](https://plaid.com/docs/api/items/index.html.md#webhook_update_acknowledged) webhook to the newly specified webhook URL. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. string The new webhook URL to associate with the Item. To remove a webhook from an Item, set to `null`. Format: `url` ```node // Update the webhook associated with an Item const request: ItemWebhookUpdateRequest = { access_token: accessToken, webhook: 'https://example.com/updated/webhook', }; try { const response = await plaidClient.itemWebhookUpdate(request); // A successful response indicates that the webhook has been // updated. An acknowledgement webhook will also be fired. const item = response.data.item; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/item/webhook/update \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "webhook": "https://example.com/updated/hook" }' ``` ```ruby # update the webhook associated with an item request = Plaid::ItemWebhookUpdateRequest.new( { access_token: accessToken, webhook: "https://example.com/updated/webhook" } ) response = client.item_webhook_update(request) ``` ```java // Update the webhook associated with an Item String webhook = "https://example.com/updated/webhook"; ItemWebhookUpdateRequest request = new ItemWebhookUpdateRequest() .accessToken(accessToken) .webhook(webhook); Response webhookResponse = client() .itemWebhookUpdate(request) .execute(); // A successful response indicates that the webhook has been // updated. An acknowledgement webhook will also be fired. ItemStatus itemStatus = webhookResponse.body().getItem(); String webhook = itemStatus.getWebhook(); ``` ```python # update the webhook associated with an item request = ItemWebhookUpdateRequest( access_token=accessToken, webhook='https://example.com/updated/webhook' ) response = client.item_webhook_update(request) ``` ```go request := plaid.NewItemWebhookUpdateRequest(accessToken) request.SetWebhook("https://plaid.com/webhook-test") resp, _, err := client.PlaidApi.ItemWebhookUpdate(ctx).ItemWebhookUpdateRequest(*request).Execute() ``` #### Response fields  object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "item": { "available_products": [ "balance", "identity", "payment_initiation", "transactions" ], "billed_products": [ "assets", "auth" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_117650", "institution_name": "Royal Bank of Plaid", "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6", "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook", "auth_method": "INSTANT_AUTH" }, "request_id": "vYK11LNTfRoAMbj" } ``` \=\*=\*=\*= #### /item/public\_token/exchange  #### Exchange public token for an access token  Exchange a Link `public_token` for an API `access_token`. Link hands off the `public_token` client-side via the `onSuccess` callback once a user has successfully created an Item. The `public_token` is ephemeral and expires after 30 minutes. An `access_token` does not expire, but can be revoked by calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The response also includes an `item_id` that should be stored with the `access_token`. The `item_id` is used to identify an Item in a webhook. The `item_id` can also be retrieved by making an [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) request. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Your `public_token`, obtained from the Link `onSuccess` callback or `/sandbox/item/public_token/create`. ```node const request: ItemPublicTokenExchangeRequest = { public_token: publicToken, }; try { const response = await plaidClient.itemPublicTokenExchange(request); const accessToken = response.data.access_token; const itemId = response.data.item_id; } catch (err) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc" }' ``` ```ruby request = Plaid::ItemPublicTokenExchangeRequest.new({ public_token: public_token }) response = client.item_public_token_exchange(request) access_token = response.access_token item_id = response.item_id ``` ```java ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response response = client() .itemPublicTokenExchange(request) .execute(); String accessToken = response.body().getAccessToken(); ``` ```python request = ItemPublicTokenExchangeRequest(public_token=public_token) response = client.item_public_token_exchange(request) access_token = response['access_token'] item_id = response['item_id'] ``` ```go exchangePublicTokenReq := plaid.NewItemPublicTokenExchangeRequest(sandboxPublicTokenResp.GetPublicToken()) exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *exchangePublicTokenReq, ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() ``` #### Response fields  string The access token associated with the Item data is being requested for. string The `item_id` value of the Item associated with the returned `access_token` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6", "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op", "request_id": "Aim3b" } ``` \=\*=\*=\*= #### /item/access\_token/invalidate  #### Invalidate access\_token  By default, the `access_token` associated with an Item does not expire and should be stored in a persistent, secure manner. You can use the [/item/access\_token/invalidate](https://plaid.com/docs/api/items/index.html.md#itemaccess_tokeninvalidate) endpoint to rotate the `access_token` associated with an Item. The endpoint returns a new `access_token` and immediately invalidates the previous `access_token`. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. ```node // Generate a new access_token for an Item, invalidating the old one const request: ItemAccessTokenInvalidateRequest = { access_token: accessToken, }; try { const response = await plaidClient.itemAccessTokenInvalidate(request); // Store the new access_token in a persistent, secure datastore const accessToken = response.data.new_access_token; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/item/access_token/invalidate \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```ruby # generate a new access_token for an item, invalidating the old one request = Plaid::ItemAccessTokenInvalidateRequest.new({ access_token: access_token }) response = client.item_access_token_invalidate(request) # store the new access_token in a persistent, secure datastore new_access_token = response.new_access_token ``` ```java // Generate a new access_token for an Item, invalidating the old one ItemAccessTokenInvalidateRequest request = new ItemAccessTokenInvalidateRequest() .accessToken(accessToken); Response response = client() .itemAccessTokenInvalidate(request) .execute(); String newAccessToken; if (response.isSuccessful()) { // Store the new access_token in a persistent, secure datastore newAccessToken = response.body().getNewAccessToken(); } ``` ```python # generate a new access_token for an item, invalidating the old one request = ItemAccessTokenInvalidateRequest(access_token=access_token) response = client.item_access_token_invalidate(request) # store the new access_token in a persistent, secure datastore new_access_token = response['new_access_token'] ``` ```go // Generate a new access_token for an Item, invalidating the old one request := plaid.NewItemAccessTokenInvalidateRequest(accessToken) response, _, err := client.PlaidApi.ItemAccessTokenInvalidate(ctx).ItemAccessTokenInvalidateRequest( *request, ).Execute() // Store the new access_token in a persistent, secure datastore newAccessToken := response.GetNewAccessToken() ``` #### Response fields  string The access token associated with the Item data is being requested for. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "new_access_token": "access-sandbox-8ab976e6-64bc-4b38-98f7-731e7a349970", "request_id": "m8MDnv9okwxFNBV" } ``` ### Webhooks  Webhooks are used to communicate changes to an Item, such as an updated webhook, or errors encountered with an Item. The error typically requires user action to resolve, such as when a user changes their password. All Item webhooks have a `webhook_type` of `ITEM`. \=\*=\*=\*= #### ERROR  Fired when an error is encountered with an Item. The error can be resolved by having the user go through Link’s update mode. #### Properties  string `ITEM` string `ERROR` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "ITEM", "webhook_code": "ERROR", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "user_id": "usr_9nSp2KuZ2x4JDw", "error": { "display_message": "The user’s OAuth connection to this institution has been invalidated.", "error_code": "ITEM_LOGIN_REQUIRED", "error_code_reason": "OAUTH_INVALID_TOKEN", "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state", "error_type": "ITEM_ERROR", "status": 400 }, "environment": "production" } ``` \=\*=\*=\*= #### LOGIN\_REPAIRED  Fired when an Item has exited the `ITEM_LOGIN_REQUIRED` state without the user having gone through the update mode flow in your app (this can happen if the user completed the update mode in a different app). If you have messaging that tells the user to complete the update mode flow, you should silence this messaging upon receiving the `LOGIN_REPAIRED` webhook. #### Properties  string `ITEM` string `LOGIN_REPAIRED` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "ITEM", "webhook_code": "LOGIN_REPAIRED", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "user_id": "usr_9nSp2KuZ2x4JDw", "environment": "production" } ``` \=\*=\*=\*= #### NEW\_ACCOUNTS\_AVAILABLE  Fired when Plaid detects a new account. Upon receiving this webhook, you can prompt your users to share new accounts with you through [update mode](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode-to-request-new-accounts) (US/CA only). If the end user has opted not to share new accounts with Plaid via their institution's OAuth settings, Plaid will not detect new accounts and this webhook will not fire. For end user accounts in the EU and UK, upon receiving this webhook, you can prompt your user to re-link their account and then delete the old Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . #### Properties  string `ITEM` string `NEW_ACCOUNTS_AVAILABLE` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "ITEM", "webhook_code": "NEW_ACCOUNTS_AVAILABLE", "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ", "user_id": "usr_9nSp2KuZ2x4JDw", "error": null, "environment": "production" } ``` \=\*=\*=\*= #### PENDING\_DISCONNECT  Fired when an Item is expected to be disconnected. The webhook will currently be fired 7 days before the existing Item is scheduled for disconnection. This can be resolved by having the user go through Link’s [update mode](http://plaid.com/docs/link/update-mode) . Currently, this webhook is fired only for US or Canadian institutions; in the UK or EU, you should continue to listed for the [PENDING\_EXPIRATION](https://plaid.com/docs/api/items/index.html.md#pending_expiration) webhook instead. #### Properties  string `ITEM` string `PENDING_DISCONNECT` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. string Reason why the item is about to be disconnected. `INSTITUTION_MIGRATION`: The institution is moving to API or to a different integration. For example, this can occur when an institution moves from a non-OAuth integration to an OAuth integration. `INSTITUTION_TOKEN_EXPIRATION`: The consent on an Item associated with a US or CA institution is about to expire. Possible values: `INSTITUTION_MIGRATION`, `INSTITUTION_TOKEN_EXPIRATION` string The date and time at which the Item is scheduled to disconnect, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "ITEM", "webhook_code": "PENDING_DISCONNECT", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "user_id": "usr_9nSp2KuZ2x4JDw", "reason": "INSTITUTION_MIGRATION", "disconnect_time": "2020-01-15T13:25:17.766Z", "environment": "production" } ``` \=\*=\*=\*= #### PENDING\_EXPIRATION  Fired when an Item’s access consent is expiring in 7 days. This can be resolved by having the user go through Link’s update mode. This webhook is fired only for Items associated with institutions in Europe (including the UK); for Items associated with institutions in the US or Canada, see [PENDING\_DISCONNECT](https://plaid.com/docs/api/items/index.html.md#pending_disconnect) instead. #### Properties  string `ITEM` string `PENDING_EXPIRATION` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "ITEM", "webhook_code": "PENDING_EXPIRATION", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "user_id": "usr_9nSp2KuZ2x4JDw", "consent_expiration_time": "2020-01-15T13:25:17.766Z", "environment": "production" } ``` \=\*=\*=\*= #### USER\_PERMISSION\_REVOKED  The `USER_PERMISSION_REVOKED` webhook may be fired when an end user has revoked the permission that they previously granted to access an Item. If the end user revoked their permissions through Plaid (such as via the Plaid Portal or by contacting Plaid Support), the webhook will fire. If the end user revoked their permissions directly through the institution, this webhook may not always fire, since some institutions’ consent portals do not trigger this webhook. To attempt to restore the Item, it can be sent through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . Depending on the exact process the end user used to revoke permissions, it may not be possible to launch update mode for the Item. If you encounter an error when attempting to create a Link token for update mode on an Item with revoked permissions, create a fresh Link token for the user. Note that when working with tokenized account numbers with Auth or Transfer, the account number provided by Plaid will no longer work for creating transfers once user permission has been revoked, except for US Bank Items. #### Properties  string `ITEM` string `USER_PERMISSION_REVOKED` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "ITEM", "webhook_code": "USER_PERMISSION_REVOKED", "error": { "error_code": "USER_PERMISSION_REVOKED", "error_message": "the holder of this account has revoked their permission for your application to access it", "error_type": "ITEM_ERROR", "status": 400 }, "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ", "user_id": "usr_9nSp2KuZ2x4JDw", "environment": "production" } ``` \=\*=\*=\*= #### USER\_ACCOUNT\_REVOKED  The `USER_ACCOUNT_REVOKED` webhook is fired when an end user has revoked access to their account on the Data Provider's portal. This webhook is currently sent only for PNC Items, but may be sent in the future for other financial institutions that allow account-level permissions revocation through their portals. Upon receiving this webhook, it is recommended to delete any Plaid-derived data you have stored that is associated with the revoked account. If you are using Auth and receive this webhook, this webhook indicates that the TAN associated with the revoked account is no longer valid and cannot be used to create new transfers. You should not create new ACH transfers for the account that was revoked until access has been re-granted. You can request the user to re-grant access to their account by sending them through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . Alternatively, they may re-grant access directly through the Data Provider's portal. After the user has re-granted access, Auth customers should call the auth endpoint again to obtain the new TAN. #### Properties  string `ITEM` string `USER_ACCOUNT_REVOKED` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. string The external account ID of the affected account string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "ITEM", "webhook_code": "USER_ACCOUNT_REVOKED", "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ", "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J", "user_id": "usr_9nSp2KuZ2x4JDw", "environment": "production" } ``` \=\*=\*=\*= #### WEBHOOK\_UPDATE\_ACKNOWLEDGED  Fired when an Item's webhook is updated. This will be sent to the newly specified webhook. #### Properties  string `ITEM` string `WEBHOOK_UPDATE_ACKNOWLEDGED` string The `item_id` of the Item associated with this webhook, warning, or error string The new webhook URL object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "ITEM", "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "error": null, "new_webhook_url": "https://plaid.com/example/webhook", "environment": "production" } ``` --- # API - Look up Dashboard users | Plaid Docs Dashboard User Audit API  ========================= #### API reference for viewing Dashboard users for Monitor and Beacon  These endpoints are used to look up a Dashboard user, as referenced in an `audit_trail` object from the [Monitor](https://plaid.com/docs/api/products/monitor/index.html.md) or [Beacon](https://plaid.com/docs/api/products/beacon/index.html.md) APIs. | Endpoints | | | --- | --- | | [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) | Retrieve information about Dashboard user | | [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) | List Dashboard users | \=\*=\*=\*= #### /dashboard\_user/get  #### Retrieve a dashboard user  The [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) endpoint provides details (such as email address) about a specific Dashboard user based on the `dashboard_user_id` field, which is returned in the `audit_trail` object of certain Monitor and Beacon endpoints. This can be used to identify the specific reviewer who performed a Dashboard action. #### Request fields  required, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. ```node const request: DashboardUserGetRequest = { dashboard_user_id: 'usr_1SUuwqBdK75GKi', }; try { const response = await client.dashboardUserGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/dashboard_user/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "dashboard_user_id": "usr_1SUuwqBdK75GKi" }' ``` ```ruby request = Plaid::DashboardUserGetRequest.new( { dashboard_user_id: 'usr_1SUuwqBdK75GKi', } ) response = client.dashboard_user_get(request) ``` ```java DashboardUserGetRequest request = new DashboardUserGetRequest() .dashboardUserId("usr_1SUuwqBdK75GKi"); Response response = client() .dashboardUserGet(request) .execute(); ``` ```python request = DashboardUserGetRequest( dashboard_user_id='usr_1SUuwqBdK75GKi', ) response = client.dashboard_user_get(request) ``` ```go request := plaid.NewDashboardUserGetRequest("usr_1SUuwqBdK75GKi") response, _, err := client.PlaidApi. DashboardUserGet(ctx). DashboardUserGetRequest(*request). Execute() if err != nil { // handle error } ``` #### Response fields  string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` string The current status of the user. Possible values: `invited`, `active`, `deactivated` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "54350110fedcbaf01234ffee", "created_at": "2020-07-24T03:26:02Z", "email_address": "user@example.com", "status": "active", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /dashboard\_user/list  #### List dashboard users  The [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) endpoint provides details (such as email address) all Dashboard users associated with your account. This can use used to audit or track the list of reviewers for Monitor, Beacon, and Identity Verification products. #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string An identifier that determines which page of results you receive. ```node try { const response = await client.dashboardUserList({}); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/dashboard_user/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}" }' ``` ```ruby response = client.dashboard_user_list({}) ``` ```java Response response = client() .dashboardUserList(new Object()) .execute(); ``` ```python request = DashboardUserListRequest( cursor='eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM', ) response = client.dashboard_user_list(request) ``` ```go request := plaid.NewDashboardUserListRequest() response, _, err := client.PlaidApi. DashboardUserList(ctx). DashboardUserListRequest(*request). Execute() if err != nil { // handle error } ``` #### Response fields  \[object\] List of dashboard users string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` string The current status of the user. Possible values: `invited`, `active`, `deactivated` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "dashboard_users": [ { "id": "54350110fedcbaf01234ffee", "created_at": "2020-07-24T03:26:02Z", "email_address": "user@example.com", "status": "active" } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` --- # API - Libraries | Plaid Docs Libraries  ========== #### Learn about libraries and SDKs to easily integrate with the Plaid APIs  All libraries for Plaid are listed below. If you've built anything that you'd be willing to share with the Plaid community, please let us know and we'll link to it here! #### Client libraries  Plaid offers official API libraries for different programming languages, which are regularly updated for breaking and non-breaking API changes. These client libraries are generated from our [OpenAPI file](https://github.com/plaid/plaid-openapi) . [(An image of "Node logo")Nodeplaid-node](https://github.com/plaid/plaid-node) [(An image of "Python logo")Pythonplaid-python](https://github.com/plaid/plaid-python) [(An image of "Ruby logo")Rubyplaid-ruby](https://github.com/plaid/plaid-ruby) [(An image of "Java logo")Javaplaid-java](https://github.com/plaid/plaid-java) [(An image of "Go logo")Goplaid-go](https://github.com/plaid/plaid-go) #### Community libraries  Explore some of the community-supported libraries available for Plaid listed below. If you built your own library, please reach out to our [support team](https://dashboard.plaid.com/support/new) to add it to this list! The best way to create your own library is by using the [Plaid OpenAPI file](https://github.com/plaid/plaid-openapi) . Note that community libraries are not officially supported by Plaid. Plaid cannot provide assistance with using these libraries or guarantee that they will be kept up-to-date with all the changes needed to support the latest modifications to the Plaid API. [Elixirby @tylerwray](https://github.com/tylerwray/elixir-plaid) [Elixirby @wfgilman](https://github.com/wfgilman/plaid-elixir) [.NETGoing.Plaid, by @viceroypenguin](https://github.com/viceroypenguin/Going.Plaid.NET) [Nodeplaid-fetch, by @heysanil. For Vercel Edge Runtime environments that don't support Axios middleware.](https://github.com/heysanil/plaid-fetch) #### Link client SDKs  For information on Plaid's front-end SDKs for web and mobile, see [Link](https://plaid.com/docs/link/index.html.md) . To learn more about installing and using Link SDKs, check out the docs pages for Link on [JavaScript and React (web)](https://plaid.com/docs/link/web/index.html.md) , [React Native](https://plaid.com/docs/link/react-native/index.html.md) , [iOS](https://plaid.com/docs/link/ios/index.html.md) , [Android](https://plaid.com/docs/link/android/index.html.md) , and [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) . Note that libraries marked as (community) are not officially supported by Plaid. Plaid cannot provide assistance with using these libraries or guarantee that they will be kept up-to-date with all the changes needed to support the latest modifications to the Plaid API. [(An image of "iOS logo")iOSplaid-link-ios](https://github.com/plaid/plaid-link-ios) [(An image of "Android logo")Androidplaid-link-android](https://github.com/plaid/plaid-link-android) [(An image of "React logo")Reactreact-plaid-link](https://github.com/plaid/react-plaid-link) [(An image of "React Native logo")React Nativereact-native-plaid-link-sdk](https://github.com/plaid/react-native-plaid-link-sdk) [JavaScriptWeb](https://plaid.com/docs/link/web/index.html.md) [Vue by Jeroen Claessens (community)](https://github.com/jclaessens97/vue-plaid-link) [Flutter (mobile)by @jorgefspereira (community)](https://github.com/jorgefspereira/plaid_flutter) [Flutter UniversalBased on Flutter (mobile), adds Flutter Desktop support. By @maxintapp (community)](https://github.com/maxint-app/plaid_universal/) [SolidJS by @thedanchez (community)](https://github.com/dsnchz/solid-plaid-link) #### Quickstart & example apps  For a listing of Plaid sample apps, see the [Resources page](https://plaid.com/docs/resources/index.html.md#sample-apps) . --- # API - Link | Plaid Docs Link endpoints  =============== #### API reference for Link tokens and webhooks  This page covers the backend flow for creating and managing Link tokens. For the Link frontend, see [Link docs](https://plaid.com/docs/link/index.html.md) . | Endpoints | | | --- | --- | | [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) | Create a token for initializing a Link session | | [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) | Get the public token and other details about a completed Link session | | See also | | | --- | --- | | [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) | Exchange a public token for an access token | | [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) | Create a public token without the Link flow (Sandbox only) | | [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) | Force an Item into an error state (Sandbox only) | | [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) | Create a session (Layer only) | | Webhooks | | | --- | --- | | [ITEM\_ADD\_RESULT](https://plaid.com/docs/api/link/index.html.md#item_add_result) | An Item was added during a Link session | | [EVENTS](https://plaid.com/docs/api/link/index.html.md#events) | Events were received from a Hosted Link session | | [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) | The user has completed a Link session | ### Endpoints  \=\*=\*=\*= #### /link/token/create  #### Create Link Token  The [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint creates a `link_token`, which is required as a parameter when initializing Link. Once Link has been initialized, it returns a `public_token`. For most Plaid products, the `public_token` is saved and exchanged for an `access_token` via [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) as part of the main Link flow. For more details, see the [Link flow overview](https://plaid.com/docs/link/index.html.md#link-flow-overview) . A `link_token` generated by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) is also used to initialize other Link flows, such as the [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow for tokens with expired credentials, or the Identity Verification flow. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The name of your application, as it should be displayed in Link. Maximum length of 30 characters. If a value longer than 30 characters is provided, Link will display "This Application" instead. Min length: `1` required, string The language that Link should be displayed in. When initializing with Identity Verification, this field is not used; for more details, see [Identity Verification supported languages](https://plaid.com/docs/identity-verification/index.html.md#supported-languages) . Supported languages are: * Danish (`'da'`) * Dutch (`'nl'`) * English (`'en'`) * Estonian (`'et'`) * French (`'fr'`) * German (`'de'`) * Hindi (`'hi'`) * Italian (`'it'`) * Latvian (`'lv'`) * Lithuanian (`'lt'`) * Norwegian (`'no'`) * Polish (`'pl'`) * Portuguese (`'pt'`) * Romanian (`'ro'`) * Spanish (`'es'`) * Swedish (`'sv'`) * Vietnamese (`'vi'`) When using a Link customization, the language configured here must match the setting in the customization, or the customization will not be applied. Min length: `1` required, \[string\] Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Institutions from all listed countries will be shown. For a complete mapping of supported products by country, see https://plaid.com/global/. For access to additional countries beyond what you have been approved for, [contact Sales](https://plaid.com/contact/) , your account manager, or support. If using Identity Verification, `country_codes` should be set to the country where your company is based, not the country where your user is located. For all other products, `country_codes` represents the location of your user's financial institution. If Link is launched with multiple country codes, only products that you are enabled for in all countries will be used by Link. While all countries are enabled by default in Sandbox, in Production only the countries you have requested access for are shown. To request access to additional countries, [file a product access Support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) via the Plaid dashboard. If using a Link customization, make sure the country codes in the customization match those specified in `country_codes`, or the customization may not be applied. If using the Auth features Instant Match, Instant Micro-deposits, Same-day Micro-deposits, Automated Micro-deposits, or Database Auth, `country_codes` must be set to `['US']`. Min items: `1` Possible values: `US`, `GB`, `ES`, `NL`, `FR`, `IE`, `CA`, `DE`, `IT`, `PL`, `DK`, `NO`, `SE`, `EE`, `LT`, `LV`, `PT`, `BE`, `AT`, `FI` object An object specifying information about the end user who will be linking their account. **Required** if `user_id` isn't included. required, string A unique ID representing the end user. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. It is currently used as a means of searching logs for the given user in the Plaid Dashboard. Min length: `1` string The user's full legal name, used for [micro-deposit based verification flows](https://plaid.com/docs/auth/coverage/index.html.md) . For a small number of customers on legacy flows, providing this field is required to enable micro-deposit-based flows. For all other customers, this field is optional. Providing the user's name in this field when using micro-deposit-based verification will streamline the end user experience, as the user will not be prompted to enter their name during the Link flow; Plaid will use the provided legal name instead. object The user's full name. Optional if using the [Identity Verification](https://plaid.com/docs/api/products/identity-verification/index.html.md) product; if not using Identity Verification, this field is not allowed. Users will not be asked for their name when this field is provided. required, string A string with at least one non-whitespace character, with a max length of 100 characters. required, string A string with at least one non-whitespace character, with a max length of 100 characters. string The user's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. If supplied, will be used when applicable to prefill phone number fields in Link for the [returning user flow](https://plaid.com/docs/link/returning-user/index.html.md) and the [Identity Verification flow](https://plaid.com/docs/identity-verification/index.html.md) . Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. string The user's email address. Can be used to prefill Link fields when used with [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) . string To be provided in the format "yyyy-mm-dd". Can be used to prefill Link fields when used with Identity Verification. Format: `date` object The user's address. Used only for Identity Verification and the Identity Match in Link workflows. If provided for Identity Verification, the user will not be shown fields to enter their address in the Identity Verification flow. If provided for Identity Match, the provided data will be used to match against the user's address. May be omitted, but if not omitted, all fields marked as required must be provided. string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. required, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. object The user's ID number. Used only for Identity Verification. If provided, the user will not be shown fields to enter their ID number in the Identity Verification flow. May be omitted, but if not omitted, all fields marked as required must be provided. required, string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . required, string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` string A `user_id` generated using `/user/create`. Required for integrations that began using Plaid Protect, Multi-Item Link, or Plaid Check Consumer Report after December 10, 2025. For more details, see [new User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . One of either the `user_id` or the `user` field is required. \[string\] List of Plaid product(s) that the linked Item must support. If launching Link in update mode, should be omitted (unless you are using update mode to add a credit product, such as Assets, Statements, Income, or Plaid Check Consumer Report, to an existing Item); at least one `product` is required otherwise. To maximize the number of institutions and accounts available, initialize Link with the minimal product set required for your use case, as the products specified will limit which institutions and account types will be available to your users in Link. Only institutions that support _all_ requested products can be selected; if a user attempts to select an institution that does not support a listed product, a "Connectivity not supported" error message will appear in Link. For each specified product, the Item connected by the user must contain at least one compatible account. For details on compatible product / account type combinations, see [the account type/product support matrix](https://plaid.com/docs/api/accounts/index.html.md#account-type--product-support-matrix) . To add products without limiting the institution list or account types, use the [optional\_products](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-optional-products) or [required\_if\_supported\_products](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-required-if-supported-products) fields. Products can also be added to an Item by calling the product endpoint after obtaining an access token; this may require the product to be listed in the [additional\_consented\_products](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-additional-consented-products) array. For details, see [Choosing when to initialize products](https://plaid.com/docs/link/initializing-products/index.html.md) . `balance` is _not_ a valid value, the Balance product does not require explicit initialization and will automatically be initialized when any other product is initialized. If launching Link with CRA products, `cra_base_reports` is required and must be included in the `products` array. Note that, unless you have opted to disable Instant Match support, institutions that support Instant Match will also be shown in Link if `auth` is specified as a product, even though these institutions do not contain `auth` in their product array. In Production, you will be billed for each product that you specify when initializing Link. Note that a product cannot be removed from an Item once the Item has been initialized with that product. To stop billing on an Item for subscription-based products, such as Liabilities, Investments, and Transactions, remove the Item via `/item/remove`. Possible values: `assets`, `auth`, `beacon`, `employment`, `identity`, `income_verification`, `identity_verification`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `protect_transactions`, `standing_orders`, `signal`, `statements`, `transactions`, `transfer`, `cra_base_report`, `cra_income_insights`, `cra_cashflow_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_network_insights`, `cra_monitoring`, `layer`, `protect_linked_bank` \[string\] List of Plaid product(s) you wish to use only if the institution and account(s) selected by the user support the product. Institutions that do not support these products will still be shown in Link. The products will only be extracted and billed if the user selects an institution and account type that supports them. There should be no overlap between this array and the `products`, `optional_products`, or `additional_consented_products` arrays. The `products` array must have at least one product. For more details on using this feature, see [Required if Supported Products](https://plaid.com/docs/link/initializing-products/index.html.md#required-if-supported-products) . Possible values: `auth`, `identity`, `investments`, `liabilities`, `transactions`, `signal`, `statements`, `protect_linked_bank`, `protect_transactions` \[string\] List of Plaid product(s) that will enhance the consumer's use case, but that your app can function without. Plaid will attempt to fetch data for these products on a best-effort basis, and failure to support these products will not affect Item creation. There should be no overlap between this array and the `products`, `required_if_supported_products`, or `additional_consented_products` arrays. The `products` array must have at least one product. For more details on using this feature, see [Optional Products](https://plaid.com/docs/link/initializing-products/index.html.md#optional-products) . Possible values: `auth`, `identity`, `investments`, `liabilities`, `signal`, `statements`, `transactions`, `cra_base_report`, `cra_income_insights`, `cra_cashflow_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_network_insights`, `cra_monitoring` \[string\] List of additional Plaid product(s) you wish to collect consent for to support your use case. These products will not be billed until you start using them by calling the relevant endpoints. `balance` is _not_ a valid value, the Balance product does not require explicit initialization and will automatically have consent collected. Institutions that do not support these products will still be shown in Link. There should be no overlap between this array and the `products` or `required_if_supported_products` arrays. If you include `signal` in `additional_consented_products`, you will need to call [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) before calling `/signal/evaluate` for the first time on an Item in order to get the most accurate results. For more details, see [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) . Possible values: `auth`, `balance_plus`, `identity`, `investments`, `investments_auth`, `liabilities`, `transactions`, `signal` string The destination URL to which any webhooks should be sent. Note that webhooks for Payment Initiation (e-wallet transactions only), Transfer, Bank Transfer (including Auth micro-deposit notification webhooks), Monitor, and Identity Verification are configured via the Dashboard instead. In update mode, this field will not have an effect; to update the webhook receiver endpoint for an existing Item, use `/item/webhook/update` instead. Format: `url` string The `access_token` associated with the Item to update or reference, used when updating, modifying, or accessing an existing `access_token`. Used when launching Link in update mode, when completing the Same-day (manual) Micro-deposit flow, or (optionally) when initializing Link for a returning user as part of the Transfer UI flow. Min length: `1` string The name of the Link customization from the Plaid Dashboard to be applied to Link. If not specified, the `default` customization will be used. When using a Link customization, the language in the customization must match the language selected via the `language` parameter, and the countries in the customization should match the country codes selected via `country_codes`. string A URI indicating the destination where a user should be forwarded after completing the Link flow; used to support OAuth authentication flows when launching Link in the browser or another app. The `redirect_uri` should not contain any query parameters. When used in Production, must be an https URI. Note that any redirect URI must also be added to the Allowed redirect URIs list in the [developer dashboard](https://dashboard.plaid.com/team/api) . If initializing on Android, `android_package_name` must be specified instead and `redirect_uri` should be left blank. string The name of your app's Android package. Required if using the `link_token` to initialize Link on Android. Any package name specified here must also be added to the Allowed Android package names setting on the [developer dashboard](https://dashboard.plaid.com/team/api) . When creating a `link_token` for initializing Link on other platforms, `android_package_name` must be left blank and `redirect_uri` should be used instead. object A map containing data used to highlight institutions in Link. string The routing number of the bank to highlight in Link. Note: in rare cases, a single routing number can be associated with multiple institutions, e.g. due to a brokerage using another institution to manage ACH on its sweep accounts. If this happens, the bank will not be highlighted in Link even if the routing number is provided. object By default, Link will provide limited account filtering: it will only display Institutions that are compatible with all products supplied in the `products` parameter of `/link/token/create`, and, if `auth` is specified in the `products` array, will also filter out accounts other than `checking`, `savings`, and `cash management` accounts on the Account Select pane. You can further limit the accounts shown in Link by using `account_filters` to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. This filtering applies to both the Account Select view (if enabled) and the Institution Select view. Institutions that do not support the selected subtypes will be omitted from Link. To indicate that all subtypes should be shown, use the value `"all"`. If the `account_filters` filter is used, any account type for which a filter is not specified will be entirely omitted from Link. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . The filter may or may not impact the list of accounts shown by the institution in the OAuth account selection flow, depending on the specific institution. If the user selects excluded account subtypes in the OAuth flow, these accounts will not be added to the Item. If the user selects only excluded account subtypes, the link attempt will fail and the user will be prompted to try again. object A filter to apply to `depository`\-type accounts required, \[string\] An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . Possible values: `checking`, `savings`, `hsa`, `cd`, `money market`, `paypal`, `prepaid`, `cash management`, `ebt`, `limited purpose checking`, `all` \[string\] An array of limited purpose types. Restricts which kinds of limited purpose checking accounts may be connected in Link to prevent users from connecting them for unsupported use cases. Required when 'limited purpose checking' is in the subtypes filter. Possible values: `RENT_MORTGAGE` object A filter to apply to `credit`\-type accounts required, \[string\] An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . Possible values: `credit card`, `paypal`, `all` object A filter to apply to `loan`\-type accounts required, \[string\] An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . Possible values: `auto`, `business`, `commercial`, `construction`, `consumer`, `home equity`, `loan`, `mortgage`, `overdraft`, `line of credit`, `student`, `other`, `all` object A filter to apply to `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier). required, \[string\] An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . Possible values: `529`, `401a`, `401k`, `403B`, `457b`, `brokerage`, `cash isa`, `crypto exchange`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `hsa`, `ira`, `isa`, `keogh`, `lif`, `life insurance`, `line of credit`, `lira`, `lrif`, `lrsp`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other annuity`, `other insurance`, `pension`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity`, `all` object A filter to apply to `other`\-type accounts required, \[string\] An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . Possible values: `other`, `all` string Used for certain legacy use cases object Specifies options for initializing Link for use with the Payment Initiation (Europe) product. This field is required if `payment_initiation` is included in the `products` array. Either `payment_id` or `consent_id` must be provided. string The `payment_id` provided by the `/payment_initiation/payment/create` endpoint. string The `consent_id` provided by the `/payment_initiation/consent/create` endpoint. object Specifies options for initializing Link for use with the Income product. This field is required if `income_verification` is included in the `products` array. string The `asset_report_id` of an asset report associated with the user, as provided by `/asset_report/create`. Providing an `asset_report_id` is optional and can be used to verify the user through a streamlined flow. If provided, the bank linking flow will be skipped. \[string\] An array of access tokens corresponding to Items that a user has previously connected with. Data from these institutions will be cross-referenced with document data received during the Document Income flow to help verify that the uploaded documents are accurate. If the `transactions` product was not initialized for these Items during link, it will be initialized after this Link session. This field should only be used with the `payroll` income source type. \[string\] The types of source income data that users will be permitted to share. Options include `bank` and `payroll`. Currently you can only specify one of these options. Possible values: `bank`, `payroll` object Specifies options for initializing Link for use with Bank Income. This field is required if `income_verification` is included in the `products` array and `bank` is specified in `income_source_types`. required, integer The number of days of data to request for the Bank Income product Minimum: `1` Maximum: `731` deprecated, boolean Whether to enable multiple Items to be added in the Link session. This setting is deprecated and has been replaced by the more general `enable_multi_item_link` setting, which supports all products. Default: `false` object Specifies options for initializing Link for use with Payroll Income (including Document Income). Further customization options for Document Income, such as customizing which document types may be uploaded, are also available via the [Link Customization pane](https://dashboard.plaid.com/link) in the Dashboard. (Requires Production enablement.) \[string\] The types of payroll income verification to enable for the Link session. If none are specified, then users will see both document and digital payroll income. Possible values: `payroll_digital_income`, `payroll_document_income` boolean An identifier to indicate whether the income verification Link token will be used for update mode. This field is only relevant for participants in the Payroll Income Refresh beta. Default: `false` string Uniquely identify a payroll income Item to update with. This field is only relevant for participants in the Payroll Income Refresh beta. \[string\] The types of analysis to enable for document uploads. If this field is not provided, then docs will undergo OCR parsing only. Possible values: `ocr`, `risk_signals` \[object\] A list of user stated income sources string The employer corresponding to an income source specified by the user string The income category for a specified income source Possible values: `OTHER`, `SALARY`, `UNEMPLOYMENT`, `CASH`, `GIG_ECONOMY`, `RENTAL`, `CHILD_SUPPORT`, `MILITARY`, `RETIREMENT`, `LONG_TERM_DISABILITY`, `BANK_INTEREST` number The income amount paid per cycle for a specified income source Format: `double` number The income amount paid annually for a specified income source Format: `double` string The pay type - `GROSS`, `NET`, or `UNKNOWN` for a specified income source Possible values: `UNKNOWN`, `GROSS`, `NET` string The pay frequency of a specified income source Possible values: `UNKNOWN`, `WEEKLY`, `BIWEEKLY`, `SEMI_MONTHLY`, `MONTHLY` object Specifies options for initializing Link for use with Plaid Check products required, integer The number of days of history to include in Plaid Check products. Maximum is 731; minimum is 180. If a value lower than 180 is provided, a minimum of 180 days of history will be requested. Maximum: `731` integer The minimum number of days of data required for the report to be successfully generated. Maximum: `184` string Client-generated identifier, which can be used by lenders to track loan applications. object Specifies options for initializing Link for use with the Credit Partner Insights product. object The versions of Prism products to evaluate string The version of Prism FirstDetect. If not specified, will default to v3. Possible values: `3`, `null` string The version of Prism Detect Possible values: `4.1`, `4`, `null` string The version of Prism CashScore. If not specified, will default to v3. Possible values: `4.1`, `4`, `3`, `null` string The version of Prism Extend Possible values: `4.1`, `4`, `null` string The version of Prism Insights. If not specified, will default to v3. Possible values: `4.1`, `4`, `3`, `null` object Specifies options for initializing Link for use with the Base Report product, specifically the `client_report_id`. string Client-generated identifier, which can be used by lenders to track loan applications. object Specifies options for initializing Link to create reports that can be shared with GSEs for mortgage verification. required, \[string\] Specifies which types of reports should be made available to GSEs. Possible values: `VOA`, `EMPLOYMENT_REFRESH` boolean Indicates that the report must include identity information. If identity information is not available, the report will fail. object Specifies options for initializing Link for use with the Cashflow Insights product. string The version of cashflow attributes. Required if using Cash Flow Insights. Possible values: `CFI1` object Specifies options for initializing Link for use with the CRA LendScore product. string The version of the LendScore to use. Required if using LendScore. Possible values: `LS1` object Specifies options for initializing Link for use with the CRA Network Insights product. string The version of Network Insights. Required if using Network Insights. Possible values: `NI1` boolean Indicates that investment data should be extracted from the linked account(s). object Specifies options for initializing Link for use with the CRA Income Insights product. object Filters the returned income streams based on the specified income categories. If no filters are requested, streams from the following default set of categories are returned: * `EARNED_INCOME.*` (`EARNED_INCOME.SALARY`, `EARNED_INCOME.GIG_ECONOMY`, `EARNED_INCOME.SELF_EMPLOYED`) * `BENEFITS.DISABILITY` * `RETIREMENT.*` (`RETIREMENT.GOVERNMENT_DERIVED`, `RETIREMENT.PRIVATE_RETIREMENT`, `RETIREMENT.PLAN_DISTRIBUTION`) The final list of income categories is generated by adding the `included_categories`, then removing the `excluded_categories`. Priority is given to `excluded_categories` in the case of collisions. Filter patterns supported: * `*`: All categories * `PRIMARY.*`: All categories within the specified primary category * `PRIMARY.SECONDARY`: A specific income category For a list of income categories, see the [Income V2 Category Taxonomy](https://plaid.com/documents/income-v2-category-taxonomy.csv) . required, \[string\] Includes income streams matching the specified categories. \[string\] Excludes income streams matching the specified categories. required, string The version of Income Insights to use. Possible values: `II2` string Describes the reason you are generating a Consumer Report for this user. When calling `/link/token/create`, this field is required when using Plaid Check (CRA) products; invalid if not using Plaid Check (CRA) products. `ACCOUNT_REVIEW_CREDIT`: In connection with a consumer credit transaction for the review or collection of an account pursuant to FCRA Section 604(a)(3)(A). `ACCOUNT_REVIEW_NON_CREDIT`: For a legitimate business need of the information to review a non-credit account provided primarily for personal, family, or household purposes to determine whether the consumer continues to meet the terms of the account pursuant to FCRA Section 604(a)(3)(F)(2). `EXTENSION_OF_CREDIT`: In connection with a credit transaction initiated by and involving the consumer pursuant to FCRA Section 604(a)(3)(A). `LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING`: For a legitimate business need in connection with a business transaction initiated by the consumer primarily for personal, family, or household purposes in connection with a property rental assessment pursuant to FCRA Section 604(a)(3)(F)(i). `LEGITIMATE_BUSINESS_NEED_OTHER`: For a legitimate business need in connection with a business transaction made primarily for personal, family, or household initiated by the consumer pursuant to FCRA Section 604(a)(3)(F)(i). `WRITTEN_INSTRUCTION_PREQUALIFICATION`: In accordance with the written instructions of the consumer pursuant to FCRA Section 604(a)(2), to evaluate an application’s profile to make an offer to the consumer. `WRITTEN_INSTRUCTION_OTHER`: In accordance with the written instructions of the consumer pursuant to FCRA Section 604(a)(2), such as when an individual agrees to act as a guarantor or assumes personal liability for a consumer, business, or commercial loan. `ELIGIBILITY_FOR_GOVT_BENEFITS`: In connection with an eligibility determination for a government benefit where the entity is required to consider an applicant’s financial status pursuant to FCRA Section 604(a)(3)(D). Possible values: `ACCOUNT_REVIEW_CREDIT`, `ACCOUNT_REVIEW_NON_CREDIT`, `EXTENSION_OF_CREDIT`, `LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING`, `LEGITIMATE_BUSINESS_NEED_OTHER`, `WRITTEN_INSTRUCTION_PREQUALIFICATION`, `WRITTEN_INSTRUCTION_OTHER`, `ELIGIBILITY_FOR_GOVT_BENEFITS` object Specifies options for initializing Link for use with the Auth product. This field can be used to enable or disable extended Auth flows for the resulting Link session. Omitting any field will result in a default that can be configured by your account manager. The default behavior described in the documentation is the default behavior that will apply if you have not requested your account manager to apply a different default. If you have enabled the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , the settings enabled there will override any settings in this object. boolean Specifies whether Auth Type Select is enabled for the Link session, allowing the end user to choose between linking via a credentials-based flow (i.e. Instant Auth, Instant Match, Automated Micro-deposits) or a manual flow that does not require login (all other Auth flows) prior to selecting their financial institution. Default behavior is `false`. boolean Specifies whether the Link session is enabled for the Automated Micro-deposits flow. Default behavior is `false`. boolean Specifies whether the Link session is enabled for the Instant Match flow. Instant Match is enabled by default. Instant Match can be disabled by setting this field to `false`. boolean Specifies whether the Link session is enabled for the Same Day Micro-deposits flow. Default behavior is `false`. boolean Specifies whether the Link session is enabled for the Instant Micro-deposits flow. Default behavior for Plaid teams created after November 2023 is `false`; default behavior for Plaid teams created before that date is `true`. string Specifies what type of [Reroute to Credentials](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#removing-manual-verification-entry-points-with-reroute-to-credentials) pane should be used in the Link session for the Same Day Micro-deposits flow. Default behavior is `OPTIONAL`. Possible values: `OFF`, `OPTIONAL`, `FORCED` deprecated, boolean Database Match has been deprecated and replaced with Database Auth. Use the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) to enable Database Auth. deprecated, boolean Database Insights has been deprecated and replaced with Database Auth. Use the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) to enable Database Auth. boolean Specifies whether the Link session is enabled for SMS micro-deposits verification. Default behavior is `true`. object Specifies options for initializing Link for use with the Transfer product. string The `id` returned by the `/transfer/intent/create` endpoint. string The `id` returned by the `/transfer/authorization/create` endpoint. Used to indicate Link session to complete required user action in order to make a decision for the authorization. If set, `access_token` can be omitted. object Specifies options for initializing Link for [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . boolean If `true`, enables [update mode with Account Select](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode-to-request-new-accounts) for institutions in the US and Canada that do not use OAuth, or that use OAuth but do not have their own account selection flow. For institutions in the US that have an OAuth account selection flow (i.e. most OAuth-enabled institutions), update mode with Account Select will always be enabled, regardless of the value of this field. Default: `false` boolean If `true`, a `user_token` must also be provided, and Link will open in update mode for the given user. Default: `false` \[string\] An array of `item_id`s associated with the user to be updated in update mode. If empty or `null`, this field will default to initializing update mode for the most recent unhealthy Item associated with the user. A `user_token` must also be provided to use this field. object Specifies option for initializing Link for use with the Identity Verification product. required, string ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive. boolean A flag specifying whether the end user has already agreed to a privacy policy specifying that their data will be shared with Plaid for verification purposes. If `gave_consent` is set to `true`, the `accept_tos` step will be marked as `skipped` and the end user's session will start at the next step requirement. Default: `false` object Specifies options for initializing Link for use with the Statements product. This field is required for the statements product. required, string The start date for statements, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) "YYYY-MM-DD" format, e.g. "2020-10-30". Format: `date` required, string The end date for statements, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) "YYYY-MM-DD" format, e.g. "2020-10-30". You can request up to two years of data. Format: `date` object Configuration parameters for the Investments product boolean If `true`, allow self-custody crypto wallets to be added without requiring signature verification. Defaults to `false`. boolean If `true`, allow users to manually enter Investments account and holdings information. Defaults to `false`. object Configuration parameters for the Investments Move product boolean If `true`, show institutions that use the manual entry fallback flow. Default: `false` boolean If `true`, show institutions that use the masked number match fallback flow. Default: `false` boolean If `true`, show institutions that use the stated account number fallback flow. Default: `false` object Configuration parameters for Hosted Link. To enable the session for Hosted Link, send this object in the request. It can be empty. string How Plaid should deliver the Plaid Link session to the customer. Only available to customers enabled for Link Delivery (beta). To request Link Delivery access, contact your account manager. 'sms' will deliver via SMS. Must pass `user.phone_number`. 'email' will deliver via email. Must pass `user.email_address`. In the Sandbox environment, this field will be ignored; use the Production environment to test Link Delivery instead. Possible values: `sms`, `email` string URI that Hosted Link will redirect to upon completion of the Link flow. This will only occur in Hosted Link sessions, not in other implementation methods. integer How many seconds the link will be valid for. Must be positive. Cannot be longer than 21 days. The default lifetime is 7 days for links delivered by email, 1 day for links delivered via SMS, and 30 minutes for links not sent via Plaid Link delivery. This parameter will override the value of all three link types. boolean This indicates whether the client is opening hosted Link in a mobile app in an `AsWebAuthenticationSession` or Chrome custom tab. Default: `false` object Configuration parameters for the Transactions product integer The maximum number of days of transaction history to request for the Transactions product. The more transaction history is requested, the longer the historical update poll will take. The default value is 90 days. In Production, if a value under 30 is provided, a minimum of 30 days of history will be requested. Once Transactions has been added to an Item, this value cannot be updated. Customers using [Recurring Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) should request at least 180 days of history for optimal results. Minimum: `1` Maximum: `730` Default: `90` object Identity object used to specify document upload boolean Used to specify whether the Link session is Identity Document Upload \[string\] An array of `account_ids`. Currently can only contain one `account_id`. Must be populated if using Document Upload. \[string\] An array of parsing configurations. Valid parsing configurations are `ocr` and `risk_signals`. If parsing configurations are omitted, defaults to `ocr` Possible values: `ocr`, `risk_signals` boolean If `true`, enable linking multiple items in the same Link session. Defaults to `false`. string A user token generated using `/user/create`. Any Item created during the Link session will be associated with the user. Integrations that began using Plaid Protect, Multi-Item Link, or Plaid Check Consumer Report before December 10, 2025 use this field instead of the `user_id`. ```node const request: LinkTokenCreateRequest = { loading_sample: true }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```python request = LinkTokenCreateRequest( loading_sample=True ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "loading_sample": true }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { loading_sample: true } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .loadingSample(true); Response response = client .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```go request := plaid.NewLinkTokenCreateRequest( "Sample App App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetLoadingSample(true) linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := linkTokenCreateResp.GetLinkToken(); ``` #### Response fields  string A `link_token`, which can be supplied to Link in order to initialize it and receive a `public_token`, which can be exchanged for an `access_token`. string The expiration date and time for the `link_token`, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. By default, a `link_token` created to generate a `public_token` that will be exchanged for a new `access_token` expires after 4 hours, and a `link_token` created for an existing Item (such as when updating an existing `access_token` by launching Link in update mode) expires after 30 minutes. If using [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) , the `link_token` will expire at the same time as the Hosted Link URL, and you can customize the duration using the `hosted_link.url_lifetime_seconds` option in the request. If using Link Delivery (beta), the `link_token` will expire by default after 24 hours if sent via SMS and after 7 days if sent via email. If using Identity Verification, Link token expiration will not be enforced; an Identity Verification Link session can be created with an expired Link token. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. string A URL of a Plaid-hosted Link flow that will use the Link token returned by this request. Only present if the session is enabled for Hosted Link. To enable the session for Hosted Link, send a `hosted_link` object in the request. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . Response Object ```json { "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176", "expiration": "2020-03-27T12:56:34Z", "request_id": "XQVgFigpGHXkb0b" } ``` \=\*=\*=\*= #### /link/token/get  #### Get Link Token  The [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint gets information about a Link session, including all callbacks fired during the session along with their metadata, including the public token. This endpoint is used with Link flows that don't provide a public token via frontend callbacks, such as the [Hosted Link flow](https://plaid.com/docs/link/hosted-link/index.html.md) and the [Multi-Item Link flow](https://plaid.com/docs/link/multi-item-link/index.html.md) . It also can be useful for debugging purposes. By default, this endpoint will only return complete event data for Hosted Link sessions. To use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to retrieve event data for non-Hosted-Link sessions, contact your account manager to request that your account be enabled for Link events. If you do not have an account manager, you can submit this request via a support ticket. Enablement for Link events will also cause you to receive additional webhooks related to Link events, such as the `SESSION_FINISHED` and `EVENTS` webhook. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string A `link_token` from a previous invocation of `/link/token/create` ```ruby request = Plaid::LinkTokenGetRequest.new({ link_token: link_token }) response = client.link_token_get(request) ``` ```go linkTokenGetRequest := plaid.NewLinkTokenGetRequest(linkToken) linkTokenGetResp, _, err := client.PlaidApi.LinkTokenGet(ctx).LinkTokenGetRequest(*linkTokenGetRequest).Execute() ``` ```java LinkTokenGetRequest request = new LinkTokenGetRequest() .linkToken(linkToken); Response getResponse = client() .linkTokenGet(request) .execute(); ``` ```python request = LinkTokenGetRequest(link_token=link_token) response = client.link_token_get(request) ``` ```node const request: LinkTokenGetRequest = { link_token: linkToken, }; try { const response = await plaidClient.linkTokenGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/get -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "link_token": "${LINK_TOKEN}" }' ``` #### Response fields  string A `link_token`, which can be supplied to Link in order to initialize it and receive a `public_token`, which can be exchanged for an `access_token`. nullable, string The creation timestamp for the `link_token`, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` nullable, string The expiration timestamp for the `link_token`, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` \[object\] Information about Link sessions created using this `link_token`. Session data will be provided for up to six hours after the session has ended. string The unique ID for the link session. string The timestamp at which the link session was first started, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` nullable, string The timestamp at which the link session was finished, if available, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` deprecated, nullable, object An object representing an [onSuccess](https://plaid.com/docs/link/web/index.html.md#onsuccess) callback from Link. This field is returned only for legacy integrations and is deprecated in favor of [results.item\_add\_results](https://plaid.com/docs/api/link/index.html.md#link-token-get-response-link-sessions-results-item-add-results) which can support multiple public tokens in a single Link session, for flows such as multi-Item Link. If you are receiving `on_success`, contact your Account Manager to migrate to `results.item_add_results` instead. string Displayed once a user has successfully linked their Item. nullable, object Displayed once a user has successfully linked their Item. nullable, object An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. string The full institution name, such as `'Wells Fargo'` string The Plaid institution identifier \[object\] A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, `accounts` will only include selected accounts. string The Plaid `account_id` string The official account name nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts. It may also not match the mask that the bank displays to the user. string The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values string The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values nullable, string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. deprecated, nullable, string If micro-deposit verification was being used, indicates the user's selection when asked if the account being verified is a `business` or `personal` account. This field is deprecated as Plaid no longer collects this information during the micro-deposit flow. To see whether an account is business or personal, use the `holder_category` field instead. string A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround. nullable, string The status of a transfer. Returned only when [Transfer UI](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md) is implemented. * `COMPLETE` – The transfer was completed. * `INCOMPLETE` – The transfer could not be completed. For help, see [Troubleshooting transfers](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md#troubleshooting-transfer-ui) . Possible values: `COMPLETE`, `INCOMPLETE`, `null` deprecated, nullable, object An object representing an [onExit](https://plaid.com/docs/link/web/index.html.md#onexit) callback from Link. This field is returned only for legacy implementations and has been deprecated in favor of [exit](https://plaid.com/docs/api/link/index.html.md#link-token-get-response-link-sessions-exit) , for improved naming consistency. If you are receiving this field, contact your Account Manager to migrate to the newer `exit` field. nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. nullable, object Displayed if a user exits Link without successfully linking an Item. nullable, object An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. string The full institution name, such as `Wells Fargo` string The Plaid institution identifier string The point at which the user exited the Link flow. One of the following values. User prompted to answer security questions User prompted to answer multiple choice question(s) User prompted to provide a one-time passcode User prompted to select a device on which to receive a one-time passcode User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution User prompted to select one or more financial accounts to share User prompted to enter an OAuth flow User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution User exited the Link flow after discovering their selected institution is no longer supported by Plaid string A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround. string The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. nullable, object An object representing an [onExit](https://plaid.com/docs/link/web/index.html.md#onexit) callback from Link. If you are not receiving this field and are instead receiving the deprecated `on_exit` field, contact your Account Manager to update your integration. nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. nullable, object Displayed if a user exits Link without successfully linking an Item. nullable, object An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. string The full institution name, such as `Wells Fargo` string The Plaid institution identifier string The point at which the user exited the Link flow. One of the following values. User prompted to answer security questions User prompted to answer multiple choice question(s) User prompted to provide a one-time passcode User prompted to select a device on which to receive a one-time passcode User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution User prompted to select one or more financial accounts to share User prompted to enter an OAuth flow User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution User exited the Link flow after discovering their selected institution is no longer supported by Plaid string A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround. string The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. \[object\] List of customer-related Link events string Event name string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. string UUID that can be used to deduplicate events object Metadata about an event that occurred while the user was going through Link string The error code that the user encountered. Emitted by `ERROR`, `EXIT`. string The error message that the user encountered. Emitted by: `ERROR`, `EXIT`. string The error type that the user encountered. Emitted by: `ERROR`, `EXIT`. string The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT`. string The ID of the selected institution. Emitted by: all events. string The name of the selected institution. Emitted by: all events. string The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`. string The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events. string If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: `SUBMIT_MFA` and `TRANSITION_VIEW` when `view_name` is `MFA`. string The name of the view that is being transitioned to. Emitted by: `TRANSITION_VIEW`. string Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are `phoneotp` or `password`; if selection is used to describe the selected Auth Type Select flow, then possible values are `flow_type_manual` or `flow_type_instant`. Emitted by: `MATCHED_SELECT_VERIFY_METHOD` and `SELECT_AUTH_TYPE`. string The name of the selected brand. string The reason this institution was matched. This will be either `returning_user` or `routing_number` if emitted by `MATCHED_SELECT_INSTITUTION`. Otherwise, this will be `SAVED_INSTITUTION` or `AUTO_SELECT_SAVED_INSTITUTION` if emitted by `SELECT_INSTITUTION`. string The routing number submitted by user at the micro-deposits routing number pane. Emitted by `SUBMIT_ROUTING_NUMBER`. string The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, `account_number_mask` is empty. Emitted by `SUBMIT_ACCOUNT_NUMBER`. nullable, object The set of results for a Link session. \[object\] The set of Item adds for the Link session. If you are not receiving this field and are instead receiving the deprecated `on_success` field, contact your Account Manager to update your integration. string Returned once a user has successfully linked their Item. \[object\] A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, `accounts` will only include selected accounts. string The Plaid `account_id` string The official account name nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts. It may also not match the mask that the bank displays to the user. string The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values string The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values nullable, string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. deprecated, nullable, string If micro-deposit verification was being used, indicates the user's selection when asked if the account being verified is a `business` or `personal` account. This field is deprecated as Plaid no longer collects this information during the micro-deposit flow. To see whether an account is business or personal, use the `holder_category` field instead. nullable, object An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. string The full institution name, such as `'Wells Fargo'` string The Plaid institution identifier \[object\] The set of Plaid Check Item adds for the Link session. string The Plaid Check Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. The `item_id` is case-sensitive. \[object\] A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, `accounts` will only include selected accounts. string The Plaid `account_id` string The official account name nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts. It may also not match the mask that the bank displays to the user. string The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values string The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values nullable, string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. deprecated, nullable, string If micro-deposit verification was being used, indicates the user's selection when asked if the account being verified is a `business` or `personal` account. This field is deprecated as Plaid no longer collects this information during the micro-deposit flow. To see whether an account is business or personal, use the `holder_category` field instead. nullable, object An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. string The full institution name, such as `'Wells Fargo'` string The Plaid institution identifier \[object\] The set of Plaid Check Item updates for the Link session. string The Plaid Check Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. The `item_id` is case-sensitive. \[object\] A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, `accounts` will only include selected accounts. string The Plaid `account_id` string The official account name nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts. It may also not match the mask that the bank displays to the user. string The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values string The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values nullable, string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. deprecated, nullable, string If micro-deposit verification was being used, indicates the user's selection when asked if the account being verified is a `business` or `personal` account. This field is deprecated as Plaid no longer collects this information during the micro-deposit flow. To see whether an account is business or personal, use the `holder_category` field instead. nullable, object An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. string The full institution name, such as `'Wells Fargo'` string The Plaid institution identifier \[object\] The set of bank income verifications for the Link session. string Status of the Bank Income Link session. `APPROVED`: User has approved and verified their income `NO_DEPOSITS_FOUND`: We attempted, but were unable to find any income in the connected account. `USER_REPORTED_NO_INCOME`: The user explicitly indicated that they don't receive income in the connected account. `STARTED`: The user began the bank income portion of the link flow. `INTERNAL_ERROR`: The user encountered an internal error. Possible values: `APPROVED`, `NO_DEPOSITS_FOUND`, `USER_REPORTED_NO_INCOME` string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, object An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. string The full institution name, such as `'Wells Fargo'` string The Plaid institution identifier \[object\] The set of payroll income verifications for the Link session. integer The number of paystubs retrieved from a payroll provider. integer The number of W-2s retrieved from a payroll provider. nullable, object An institution object. If the Item was created via Same-Day or Instant micro-deposit verification, will be `null`. string The full institution name, such as `'Wells Fargo'` string The Plaid institution identifier nullable, object The details of a document income verification in Link integer The number of paystubs uploaded by the user. integer The number of w2s uploaded by the user. integer The number of bank statements uploaded by the user. integer The number of 1099s uploaded by the user nullable, object The details of a document upload CRA session in link integer The number of bank statements uploaded by the user. object An object specifying the arguments originally provided to the `/link/token/create` call. \[string\] The `products` specified in the `/link/token/create` call. Possible values: `assets`, `auth`, `employment`, `identity`, `income_verification`, `identity_verification`, `investments`, `liabilities`, `payment_initiation`, `standing_orders`, `transactions`, `transfer` nullable, string The `webhook` specified in the `/link/token/create` call. Format: `url` \[string\] The `country_codes` specified in the `/link/token/create` call. Possible values: `US`, `GB`, `ES`, `NL`, `FR`, `IE`, `CA`, `DE`, `IT`, `PL`, `DK`, `NO`, `SE`, `EE`, `LT`, `LV`, `PT`, `BE`, `AT`, `FI` nullable, string The `language` specified in the `/link/token/create` call. object A map containing data used to highlight institutions in Link. string The routing number of the bank to highlight in Link. Note: in rare cases, a single routing number can be associated with multiple institutions, e.g. due to a brokerage using another institution to manage ACH on its sweep accounts. If this happens, the bank will not be highlighted in Link even if the routing number is provided. object The `account_filters` specified in the original call to `/link/token/create`. object A filter to apply to `depository`\-type accounts \[string\] An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . Possible values: `checking`, `savings`, `hsa`, `cd`, `money market`, `paypal`, `prepaid`, `cash management`, `ebt`, `limited purpose checking`, `all` \[string\] An array of limited purpose types. Restricts which kinds of limited purpose checking accounts may be connected in Link to prevent users from connecting them for unsupported use cases. Required when 'limited purpose checking' is in the subtypes filter. Possible values: `RENT_MORTGAGE` object A filter to apply to `credit`\-type accounts \[string\] An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . Possible values: `credit card`, `paypal`, `all` object A filter to apply to `loan`\-type accounts \[string\] An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . Possible values: `auto`, `business`, `commercial`, `construction`, `consumer`, `home equity`, `loan`, `mortgage`, `overdraft`, `line of credit`, `student`, `other`, `all` object A filter to apply to `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier). \[string\] An array of account subtypes to display in Link. If not specified, all account subtypes will be shown. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . Possible values: `529`, `401a`, `401k`, `403B`, `457b`, `brokerage`, `cash isa`, `crypto exchange`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `hsa`, `ira`, `isa`, `keogh`, `lif`, `life insurance`, `line of credit`, `lira`, `lrif`, `lrsp`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other annuity`, `other insurance`, `pension`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity`, `all` nullable, string The `redirect_uri` specified in the `/link/token/create` call. nullable, string The `client_name` specified in the `/link/token/create` call. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "created_at": "2024-07-29T20:22:21Z", "expiration": "2024-07-29T20:52:22Z", "link_sessions": [ { "events": [ { "event_id": "8b2b5d28-79ec-468b-bbce-f8bd34be635a", "event_metadata": { "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "Nnclj9HntPMu5dm" }, "event_name": "HANDOFF", "timestamp": "2024-07-29T20:23:59Z" }, { "event_id": "12a888e0-da26-4c38-8ded-2992bc78c246", "event_metadata": { "request_id": "Nnclj9HntPMu5dm" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T20:23:59Z" }, { "event_id": "6557bdf1-a20a-43b0-8fed-c8b671e2f478", "event_metadata": { "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "sR4EGcU8zniznXi" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T20:23:56Z" }, { "event_id": "c6745f4c-d8fa-4103-8a65-7b995c60809e", "event_metadata": { "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "4LYDWkxfJ0htDA4" }, "event_name": "SUBMIT_CREDENTIALS", "timestamp": "2024-07-29T20:23:55Z" }, { "event_id": "2610fa06-e765-4c9e-8948-63048d451dbf", "event_metadata": { "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "4LYDWkxfJ0htDA4" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T20:23:23Z" }, { "event_id": "54b87deb-60a7-4f50-9326-293840090b72", "event_metadata": { "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "FTEFiPeL9OstwL4" }, "event_name": "SELECT_INSTITUTION", "timestamp": "2024-07-29T20:23:23Z" }, { "event_id": "6b285180-0bac-4ccc-bec0-d4ed75c253d2", "event_metadata": { "request_id": "FTEFiPeL9OstwL4" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T20:23:20Z" }, { "event_id": "239a6000-da50-4319-99f7-919378b7db53", "event_metadata": { "request_id": "WFgwgGivjBbwOb9" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T20:23:17Z" }, { "event_id": "0a523744-5003-4578-8414-c87e06ef8ca9", "event_metadata": { "institution_id": "ins_127989", "institution_name": "Bank of America", "request_id": "WFgwgGivjBbwOb9" }, "event_name": "HANDOFF", "timestamp": "2024-07-29T20:23:17Z" }, { "event_id": "ff44d52a-51ef-4987-b7d0-b6497dfa93cd", "event_metadata": { "institution_id": "ins_127989", "institution_name": "Bank of America", "request_id": "uqA0Vq8zuKlsB2y" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T20:23:14Z" }, { "event_id": "e0d7c1dc-8e7e-4361-893f-d6c2d2f050ab", "event_metadata": { "institution_id": "ins_127989", "institution_name": "Bank of America", "request_id": "dTGtMHbK21BLrsp" }, "event_name": "OPEN_OAUTH", "timestamp": "2024-07-29T20:22:49Z" }, { "event_id": "de87a1c0-666e-4d95-88d8-1163f6bf20f1", "event_metadata": { "institution_id": "ins_127989", "institution_name": "Bank of America", "request_id": "dTGtMHbK21BLrsp" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T20:22:47Z" }, { "event_id": "6edc2c59-96cd-4dee-a86b-140ddfd3076e", "event_metadata": { "institution_id": "ins_127989", "institution_name": "Bank of America", "request_id": "BxBukZsBEmxZw0I" }, "event_name": "SELECT_INSTITUTION", "timestamp": "2024-07-29T20:22:46Z" }, { "event_id": "d176ab57-26d2-45ee-a0fe-67daf0cf0cb0", "event_metadata": { "request_id": "BxBukZsBEmxZw0I" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T20:22:43Z" }, { "event_id": "b8be9c3d-7ac5-4851-bd92-0638cb63bdeb", "event_metadata": { "request_id": "UtqR09RKzJ1gcEx" }, "event_name": "SKIP_SUBMIT_PHONE", "timestamp": "2024-07-29T20:22:42Z" }, { "event_id": "7144cca7-533b-4dfc-81ed-f78a750ba95f", "event_metadata": { "request_id": "UtqR09RKzJ1gcEx" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T20:22:40Z" }, { "event_id": "e6a6dcc0-6bbf-4871-8d59-0c3a5eccff53", "event_metadata": { "request_id": "FTiagIVmxfqbevM" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T20:22:39Z" } ], "finished_at": "2024-07-29T20:24:05.330312653Z", "link_session_id": "43face8b-a5c2-42a4-adec-4a4ec589eb46", "on_success": { "metadata": { "accounts": [ { "class_type": null, "id": "DXzZ94ZG9vhaZy8BvyZRSQ4jJwwlkNS3RwoeX", "mask": "0000", "name": "Plaid Checking", "subtype": "checking", "type": "depository", "verification_status": null }, { "class_type": null, "id": "VJyR7wRm79TNGEKxpEG9fjpJ1mmM5Bt9ymVkR", "mask": "1111", "name": "Plaid Saving", "subtype": "savings", "type": "depository", "verification_status": null }, { "class_type": null, "id": "wZXnexn1eoH6LNWmMNL4hqkPB55ndjHPRNp93", "mask": "9999", "name": "Plaid Business Credit Card", "subtype": "credit card", "type": "credit", "verification_status": null } ], "institution": { "institution_id": "ins_127989", "name": "Bank of America" }, "link_session_id": "43face8b-a5c2-42a4-adec-4a4ec589eb46", "transfer_status": null }, "public_token": "public-sandbox-3b9687f0-3abd-4913-9889-f0ba816d4a3a" }, "results": { "item_add_results": [ { "accounts": [ { "class_type": null, "id": "DXzZ94ZG9vhaZy8BvyZRSQ4jJwwlkNS3RwoeX", "mask": "0000", "name": "Plaid Checking", "subtype": "checking", "type": "depository", "verification_status": null }, { "class_type": null, "id": "VJyR7wRm79TNGEKxpEG9fjpJ1mmM5Bt9ymVkR", "mask": "1111", "name": "Plaid Saving", "subtype": "savings", "type": "depository", "verification_status": null }, { "class_type": null, "id": "wZXnexn1eoH6LNWmMNL4hqkPB55ndjHPRNp93", "mask": "9999", "name": "Plaid Business Credit Card", "subtype": "credit card", "type": "credit", "verification_status": null } ], "institution": { "institution_id": "ins_127989", "name": "Bank of America" }, "public_token": "public-sandbox-3b9687f0-3abd-4913-9889-f0ba816d4a3a" }, { "accounts": [ { "class_type": null, "id": "qvqrX8gDvxCdyvvgGkKzSNPzDwaQGjFgyQk5Z", "mask": "4007", "name": "Checking", "subtype": "checking", "type": "depository", "verification_status": null } ], "institution": { "institution_id": "ins_20", "name": "Citizens Bank" }, "public_token": "public-sandbox-44ba202e-bf6b-45c6-a5ba-d526765626a9" } ], "cra_item_add_results": [], "cra_update_results": [], "bank_income_results": [], "payroll_income_results": [], "document_income_results": null, "protect_results": null }, "started_at": "2024-07-29T20:22:36.522196741Z" } ], "link_token": "link-sandbox-e7b6956c-1522-4823-85d2-c4ca74251949", "metadata": { "client_name": "Wonderwallet", "country_codes": [ "US" ], "initial_products": [ "transactions" ], "language": "en", "redirect_uri": null, "webhook": "https://webhook.site/dc9c138f-75de-4db1-883a-a4add4b7eb7e" }, "user_id": "usr_123456abcdef", "request_id": "Pxpgzy0Wjvn99mY" } ``` ### Webhooks  \=\*=\*=\*= #### ITEM\_ADD\_RESULT  Fired when a user successfully adds a Plaid Item during a Link session when using Hosted Link or Multi-Item Link sessions. Contains the public token for the Item. #### Properties  string `LINK` string `ITEM_ADD_RESULT` string The identifier for the Link session. string The link token used to create the Link session. string The public token corresponding to the item that was added. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "LINK", "webhook_code": "ITEM_ADD_RESULT", "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171", "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176", "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", "environment": "sandbox" } ``` \=\*=\*=\*= #### EVENTS  This webhook contains a summary of the events from a Link session and will be fired after the user finishes going through Link. If the user abandons the Link flow (i.e., closes the hosted link webpage or leaves Link open for too long without taking any action), the webhook will be fired 5-15 minutes after the last user interaction. A single Link session may occasionally generate multiple `EVENTS` webhooks. If this occurs, the new webhook will contain all previous events for the session, as well as new events that occurred since the previous `EVENTS` webhook was sent. If this occurs, events can be grouped using the `link_session_id` field and, if necessary, de-duplicated using the `event_id` field. By default, the `EVENTS` webhook is sent only for sessions where the end user goes through a Hosted Link flow (including Link Recovery flows). If you would like to receive this webhook for sessions not using Hosted Link, contact your Account Manager or Support. This enablement will also cause you to receive the `SESSION_FINISHED` webhook for non-Hosted-Link sessions and to be able to use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to receive events data for non-Hosted Link sessions. #### Properties  string `LINK` string `EVENTS` \[object\] The Link events emitted during the Link session string Event name string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. string UUID that can be used to deduplicate events object Metadata about an event that occurred while the user was going through Link string The error code that the user encountered. Emitted by `ERROR`, `EXIT`. string The error message that the user encountered. Emitted by: `ERROR`, `EXIT`. string The error type that the user encountered. Emitted by: `ERROR`, `EXIT`. string The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT`. string The ID of the selected institution. Emitted by: all events. string The name of the selected institution. Emitted by: all events. string The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`. string The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events. string If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: `SUBMIT_MFA` and `TRANSITION_VIEW` when `view_name` is `MFA`. string The name of the view that is being transitioned to. Emitted by: `TRANSITION_VIEW`. string Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are `phoneotp` or `password`; if selection is used to describe the selected Auth Type Select flow, then possible values are `flow_type_manual` or `flow_type_instant`. Emitted by: `MATCHED_SELECT_VERIFY_METHOD` and `SELECT_AUTH_TYPE`. string The name of the selected brand. string The reason this institution was matched. This will be either `returning_user` or `routing_number` if emitted by `MATCHED_SELECT_INSTITUTION`. Otherwise, this will be `SAVED_INSTITUTION` or `AUTO_SELECT_SAVED_INSTITUTION` if emitted by `SELECT_INSTITUTION`. string The routing number submitted by user at the micro-deposits routing number pane. Emitted by `SUBMIT_ROUTING_NUMBER`. string The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, `account_number_mask` is empty. Emitted by `SUBMIT_ACCOUNT_NUMBER`. string An identifier for the Link session these events occurred in string The Link token used to create the Link session these events are from API Object ```json { "environment": "sandbox", "link_session_id": "1daca4d5-9a0d-4e85-a2e9-1e905ecaa32e", "link_token": "link-sandbox-79e723b0-0e04-4248-8a33-15ceb6828a45", "webhook_code": "EVENTS", "webhook_type": "LINK", "events": [ { "event_id": "9469937a-6fac-40be-9322-f86e8c0b94ed", "event_metadata": { "request_id": "ClqZyuhovgkaQ3j" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-05-21T00:17:54Z" }, { "event_id": "4b2390cf-33a2-4078-b933-62468b9e53a5", "event_metadata": { "error_code": "INVALID_CREDENTIALS", "error_message": "the provided credentials were not correct", "error_type": "ITEM_ERROR", "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "ttK0NtGKaVAlbCR" }, "event_name": "ERROR", "timestamp": "2024-05-21T00:18:09Z" }, { "event_id": "45f76afe-f2aa-495c-a326-f37e043a1ccd", "event_metadata": { "request_id": "WRJqqeh8Hxife05" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-05-21T00:17:56Z" }, { "event_id": "978b772c-f2cc-404f-9449-2113e4671c4f", "event_metadata": { "error_code": "INVALID_CREDENTIALS", "error_message": "the provided credentials were not correct", "error_type": "ITEM_ERROR", "exit_status": "requires_credentials", "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "u1HcAeiCKtz3qmm" }, "event_name": "EXIT", "timestamp": "2024-05-21T00:18:13Z" }, { "event_id": "a873db76-aa4e-4a00-9d60-7ae08aa8e63f", "event_metadata": { "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "ttK0NtGKaVAlbCR" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-05-21T00:18:09Z" }, { "event_id": "ca85566d-5f32-4716-909f-82f3a0b6160b", "event_metadata": { "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "XRvev3cP9wYUFz5" }, "event_name": "SUBMIT_CREDENTIALS", "timestamp": "2024-05-21T00:18:07Z" }, { "event_id": "09220752-6b83-407e-baf0-f6228df16ea0", "event_metadata": { "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "WRJqqeh8Hxife05" }, "event_name": "SELECT_INSTITUTION", "timestamp": "2024-05-21T00:18:01Z" }, { "event_id": "1c75d2ee-19c1-4d1b-8600-7d06cecbb270", "event_metadata": { "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "5vc1IyBHfLkIVFx" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-05-21T00:18:12Z" }, { "event_id": "1c9c9059-c065-4362-836a-d9afb91a6125", "event_metadata": { "request_id": "MlFW5NSWtCs1KLI" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-05-21T00:17:50Z" }, { "event_id": "4f381b3f-172b-4bca-9804-c230f8d36a3b", "event_metadata": { "institution_id": "ins_20", "institution_name": "Citizens Bank", "request_id": "XRvev3cP9wYUFz5" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-05-21T00:18:02Z" }, { "event_id": "dd9d4747-d4da-4c11-88d6-b5a0e96f1886", "event_metadata": { "request_id": "ClqZyuhovgkaQ3j" }, "event_name": "SKIP_SUBMIT_PHONE", "timestamp": "2024-05-21T00:17:55Z" } ] } ``` \=\*=\*=\*= #### SESSION\_FINISHED  Contains the state of a completed Link session, along with the public token(s) if available. By default, this webhook is sent only for sessions enabled for the Hosted Link flow (including Link Recovery flows), a Multi-Item Link flow, or a Layer flow. If you would like to receive this webhook for other sessions, contact your Account Manager or Support. This enablement will also enable the `EVENTS` webhook for all Link sessions and the ability to use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to retrieve events for non-Hosted-Link sessions. #### Properties  string `LINK` string `SESSION_FINISHED` string The final status of the Link session. Will always be "SUCCESS" or "EXITED". string The identifier for the Link session. string The link token used to create the Link session. deprecated, string The public token generated by the Link session. This field has been deprecated; please use `public_tokens` instead. \[string\] The public tokens generated by the Link session. string The Plaid `user_id` of the User associated with this webhook, warning, or error. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "LINK", "webhook_code": "SESSION_FINISHED", "status": "SUCCESS", "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171", "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176", "public_tokens": [ "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" ], "environment": "sandbox" } ``` --- # API - Network | Plaid Docs Network  ======== #### API reference for the Plaid Network  | Endpoints | | | --- | --- | | [/network/status/get](https://plaid.com/docs/api/network/index.html.md#networkstatusget) | Check the status of a user in the Plaid Network | ### Endpoints  \=\*=\*=\*= #### /network/status/get  #### Check a user's Plaid Network status  The [/network/status/get](https://plaid.com/docs/api/network/index.html.md#networkstatusget) endpoint can be used to check whether Plaid has a matching profile for the user. This is useful for determining if a user is eligible for a streamlined experience, such as Layer. To access this endpoint, contact your Plaid Account Manager. Note: it is strongly recommended to check for Layer eligibility in the frontend. [/network/status/get](https://plaid.com/docs/api/network/index.html.md#networkstatusget) should only be used for checking Layer eligibility if a frontend check is not possible for your use case. For instructions on performing a frontend eligibility check, see the [Layer documentation](https://plaid.com/docs/layer/index.html.md#integration-overview) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, object An object specifying information about the end user for the network status check. required, string The user's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. string The id of a template defined in Plaid Dashboard. This field is used if you have additional criteria that you want to check against (e.g. Layer eligibility). ```bash curl -X POST https://sandbox.plaid.com/network/status/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user": { "phone_number": "+14155550015" } }' ``` ```node const request: NetworkStatusGetRequest = { user: { phone_number: '+14155550015', }, }; try { const response = await plaidClient.networkStatusGet(request); const networkStatus = response.data.network_status; } catch (error) { // handle error } ``` ```python request = NetworkStatusGetRequest( user=NetworkStatusGetRequestUser( phone_number='+14155550015', ), ) response = client.network_status_get(request) network_status = response['network_status'] ``` ```java NetworkStatusGetRequestUser user = new NetworkStatusGetRequestUser() .phoneNumber("+14155550015"); NetworkStatusGetRequest request = new NetworkStatusGetRequest() .user(user); Response response = client().networkStatusGet(request).execute(); NetworkStatus networkStatus = response.body().getNetworkStatus(); ``` ```ruby request = Plaid::NetworkStatusGetRequest.new( { user: { phone_number: '+14155550015', }, }, ) response = client.network_status_get(request) network_status = response.network_status ``` ```go var phoneNumber string = "+14155550123" user := plaid.NetworkStatusGetRequestUser{ PhoneNumber: &phoneNumber, } request := plaid.NewNetworkStatusGetRequest(user) resp, _, err := client.PlaidApi.NetworkStatusGet(ctx).NetworkStatusGetRequest(*request).Execute() if err != nil { // handle error } networkStatus := resp.GetNetworkStatus() ``` #### Response fields  string Enum representing the overall network status of the user. Possible values: `UNKNOWN`, `RETURNING_USER` nullable, object An object representing Layer-related metadata for the requested user. boolean Indicates if the user is eligible for a Layer session. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "network_status": "RETURNING_USER", "request_id": "m8MDnv9okwxFNBV" } ``` --- # API - OAuth | Plaid Docs OAuth  ====== #### API reference for Plaid OAuth endpoints  | Endpoints | | | --- | --- | | [/oauth/token](https://plaid.com/docs/api/oauth/index.html.md#oauthtoken) | Create or refresh an OAuth access token | | [/oauth/introspect](https://plaid.com/docs/api/oauth/index.html.md#oauthintrospect) | Get metadata about an OAuth token | | [/oauth/revoke](https://plaid.com/docs/api/oauth/index.html.md#oauthrevoke) | Revoke an OAuth token | These endpoints are for customers, partners and services that are integrating with Plaid's OAuth service to obtain a token for sharing consumer reports or accessing the Plaid Dashboard or other Plaid services. They are not used for the Plaid Link flow where end users connect their financial institution accounts to Plaid using a bank's OAuth service. If you are a Plaid customer trying to ensure your app supports OAuth-based bank connections, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md) instead. ### Endpoints  \=\*=\*=\*= #### /oauth/token  #### Create or refresh an OAuth access token  [/oauth/token](https://plaid.com/docs/api/oauth/index.html.md#oauthtoken) issues an access token and refresh token depending on the `grant_type` provided. This endpoint supports `Content-Type: application/x-www-form-urlencoded` as well as JSON. The fields for the form are equivalent to the fields for JSON and conform to the OAuth 2.0 specification. #### Request fields  required, string The type of OAuth grant being requested: `client_credentials` allows exchanging a client id and client secret for a refresh and access token. `refresh_token` allows refreshing an access token using a refresh token. When using this grant type, only the `refresh_token` field is required (along with the `client_id` and `client_secret`). `urn:ietf:params:oauth:grant-type:token-exchange` allows exchanging a subject token for an OAuth token. When using this grant type, the `audience`, `subject_token` and `subject_token_type` fields are required. These grants are defined in their respective RFCs. `refresh_token` and `client_credentials` are defined in RFC 6749 and `urn:ietf:params:oauth:grant-type:token-exchange` is defined in RFC 8693. Possible values: `refresh_token`, `urn:ietf:params:oauth:grant-type:token-exchange`, `client_credentials` string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body as either `secret` or `client_secret`. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body as either `secret` or `client_secret`. string A JSON string containing a space-separated list of scopes associated with this token, in the format described in [https://datatracker.ietf.org/doc/html/rfc6749#section-3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) . Currently accepted values are: `user:read` allows reading user data. `user:write` allows writing user data. `exchange` allows exchanging a token using the `urn:plaid:params:oauth:user-token` grant type. `mcp:dashboard` allows access to the MCP dashboard server. string Refresh token for OAuth string URI of the target resource server string Used when exchanging a token. The meaning depends on the `subject_token_type`: * For `urn:plaid:params:tokens:user`: Must be the same as the `client_id`. * For `urn:plaid:params:oauth:user-token`: The other `client_id` to exchange tokens to. * For `urn:plaid:params:credit:multi-user`: a `client_id` or one of the supported CRA partner URNs: `urn:plaid:params:cra-partner:experian`, `urn:plaid:params:cra-partner:fannie-mae`, or `urn:plaid:params:cra-partner:freddie-mac`. string Token representing the subject. The `subject token` must be an OAuth refresh token issued from the `/oauth/token` endpoint. The meaning depends on the `subject_token_type`. string The type of the subject token. `urn:plaid:params:tokens:user` allows exchanging a Plaid-issued user token for an OAuth token. When using this token type, `audience` must be the same as the `client_id`. `subject_token` must be a Plaid-issued user token issued from the `/user/create` endpoint. `urn:plaid:params:oauth:user-token` allows exchanging a refresh token for an OAuth token to another `client_id`. The other `client_id` is provided in `audience`. `subject_token` must be an OAuth refresh token issued from the `/oauth/token` endpoint. `urn:plaid:params:credit:multi-user` allows exchanging a Plaid-issued user token for an OAuth token. When using this token type, `audience` may be a client id or a supported CRA partner URN. `audience` supports a comma-delimited list of clients. When multiple clients are specified in the `audience` a multi-party token is created which can be used by all parties in the audience in conjunction with their `client_id` and `client_secret`. Possible values: `urn:plaid:params:tokens:user`, `urn:plaid:params:oauth:user-token`, `urn:plaid:params:credit:multi-user` ```bash curl 'https://sandbox.plaid.com/oauth/token' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "scope": "user:read", "subject_token_type":"urn:plaid:params:credit:multi-user", "audience": "urn:plaid:params:cra-partner:fannie-mae", "subject_token": "usr_9nSp2KuZ2x4JDw" }' ``` ```node const request = { grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange', scope: 'user:read', subject_token_type: 'urn:plaid:params:credit:multi-user', audience: 'urn:plaid:params:cra-partner:fannie-mae', subject_token: userId }; try { const response = await client.oauthToken(request); } catch (error) { ... } ``` ```python request = OAuthTokenRequest( grant_type="urn:ietf:params:oauth:grant-type:token-exchange", scope="user:read", subject_token_type="urn:plaid:params:credit:multi-user", audience="urn:plaid:params:cra-partner:fannie-mae", subject_token=user_id ) response = client.oauth_token(request) ``` ```java OAuthTokenRequest request = new OAuthTokenRequest() .grantType("urn:ietf:params:oauth:grant-type:token-exchange") .scope("user:read") .subjectTokenType("urn:plaid:params:credit:multi-user") .audience("urn:plaid:params:cra-partner:fannie-mae") .subjectToken(userId); Response response = plaidClient.oauthToken(request).execute(); ``` ```ruby request = Plaid::OAuthTokenRequest.new( grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange', scope: 'user:read', subject_token_type: 'urn:plaid:params:credit:multi-user', audience: 'urn:plaid:params:cra-partner:fannie-mae', subject_token: user_id ) response = client.oauth_token(request) ``` ```go request := plaid.NewOAuthTokenRequest( "urn:ietf:params:oauth:grant-type:token-exchange", ) request.SetScope("user:read") request.SetSubjectTokenType("urn:plaid:params:credit:multi-user") request.SetAudience("urn:plaid:params:cra-partner:fannie-mae") request.SetSubjectToken(user_id) ctx := context.Background() response, _, err := client.PlaidApi.OauthToken(ctx).OAuthTokenRequest(*request).Execute() if err != nil { // Handle error } ``` #### Response fields  string Access token for OAuth string Refresh token for OAuth string Type of token the access token is. Currently it is always Bearer integer Time remaining in seconds before expiration string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "access_token": "pda-RDdg0TUCB0FB25_UPIlnhA==", "refresh_token": "pdr--viXurkDg88d5zf8m6Wl0g==", "expires_in": 900, "token_type": "Bearer", "request_id": "m8MDqcS6F3lzqvP" } ``` \=\*=\*=\*= #### /oauth/introspect  #### Get metadata about an OAuth token  [/oauth/introspect](https://plaid.com/docs/api/oauth/index.html.md#oauthintrospect) returns metadata about an access token or refresh token. Note: This endpoint supports `Content-Type: application/x-www-form-urlencoded` as well as JSON. The fields for the form are equivalent to the fields for JSON and conform to the OAuth 2.0 specification. #### Request fields  required, string An OAuth token of any type (`refresh_token`, `access_token`, etc) string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body as either `secret` or `client_secret`. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body as either `secret` or `client_secret`. ```bash curl 'https://sandbox.plaid.com/oauth/introspect' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "token": "pda-RDdg0TUCB0FB25_UPIlnhA==" }' ``` ```node const request = { token: accessToken }; try { const response = await client.oauthIntrospect(request); } catch (error) { ... } ``` ```python request = OAuthIntrospectRequest( token=access_token ) response = client.oauth_introspect(request) ``` ```java OAuthIntrospectRequest request = new OAuthIntrospectRequest() .token(accessToken); Response response = plaidClient.oauthIntrospect(request).execute(); ``` ```ruby request = Plaid::OAuthIntrospectRequest.new( "token": access_token ) response = client.oauth_introspect(request) ``` ```go request := plaid.NewOAuthIntrospectRequest( accessToken, ) ctx := context.Background() response, _, err := client.PlaidApi.OauthIntrospect(ctx).OAuthIntrospectRequest(*request).Execute() if err != nil { // Handle error } ``` #### Response fields  boolean Boolean indicator of whether or not the presented token is currently active. A `true` value indicates that the token has been issued, has not been revoked, and is within the time window of validity. string A JSON string containing a space-separated list of scopes associated with this token, in the format described in [https://datatracker.ietf.org/doc/html/rfc6749#section-3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) . Currently accepted values are: `user:read` allows reading user data. `user:write` allows writing user data. `exchange` allows exchanging a token using the `urn:plaid:params:oauth:user-token` grant type. `mcp:dashboard` allows access to the MCP dashboard server. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. integer Expiration time as UNIX timestamp since January 1 1970 UTC integer Issued at time as UNIX timestamp since January 1 1970 UTC string Subject of the token string Audience of the token string Issuer of the token string Type of the token string User ID of the token string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "active": true, "scope": "user:read user:write exchange", "client_id": "68028ce48d2b0dec68747f6c", "exp": 1670000000, "iat": 1670000000, "sub": "68028ce48d2b0dec68747f6c", "aud": "https://production.plaid.com", "iss": "https://production.plaid.com", "token_type": "Bearer", "request_id": "m8MDqcS6F3lzqvP" } ``` \=\*=\*=\*= #### /oauth/revoke  #### Revoke an OAuth token  [/oauth/revoke](https://plaid.com/docs/api/oauth/index.html.md#oauthrevoke) revokes an access or refresh token, preventing any further use. If a refresh token is revoked, all access and refresh tokens derived from it are also revoked, including exchanged tokens. Note: This endpoint supports `Content-Type: application/x-www-form-urlencoded` as well as JSON. The fields for the form are equivalent to the fields for JSON and conform to the OAuth 2.0 specification. #### Request fields  required, string An OAuth token of any type (`refresh_token`, `access_token`, etc) string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body as either `secret` or `client_secret`. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body as either `secret` or `client_secret`. ```bash curl -X POST https://sandbox.plaid.com/oauth/revoke \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "token": "pda-RDdg0TUCB0FB25_UPIlnhA==" }' ``` ```node const request = { token: accessToken }; try { const response = await client.oauthRevoke(request); } catch (error) { ... } ``` ```python request = OAuthRevokeRequest( token=access_token ) response = client.oauth_revoke(request) ``` ```java OAuthRevokeRequest request = new OAuthRevokeRequest() .token(accessToken); Response response = plaidClient.oauthRevoke(request).execute(); ``` ```ruby request = Plaid::OAuthRevokeRequest.new( "token": access_token ) response = client.oauth_revoke(request) ``` ```go request := plaid.NewOAuthRevokeRequest( accessToken, ) ctx := context.Background() response, _, err := client.PlaidApi.OauthRevoke(ctx).OAuthRevokeRequest(*request).Execute() if err != nil { // Handle error } ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "m8MDqcS6F3lzqvP" } ``` --- # API - Reseller partners | Plaid Docs Partner endpoints and webhooks  =============================== #### Create and manage end customers  For general, non-reference documentation, see [Reseller partners](https://plaid.com/docs/account/resellers/index.html.md) . | Endpoints | | | --- | --- | | [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) | Create an end customer | | [/partner/customer/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomerget) | Get the status of an end customer | | [/partner/customer/oauth\_institutions/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomeroauth_institutionsget) | Get the OAuth-institution registration status for an end customer | | [/partner/customer/enable](https://plaid.com/docs/api/partner/index.html.md#partnercustomerenable) | Enable an end customer in Production | | [/partner/customer/remove](https://plaid.com/docs/api/partner/index.html.md#partnercustomerremove) | Remove an end customer | | Webhooks | | | --- | --- | | [PARTNER\_END\_CUSTOMER\_OAUTH\_STATUS\_UPDATED](https://plaid.com/docs/api/partner/index.html.md#partner_end_customer_oauth_status_updated) | Customer OAuth status updated | ### Endpoints  \=\*=\*=\*= #### /partner/customer/create  #### Creates a new end customer for a Plaid reseller.  The [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) endpoint is used by reseller partners to create end customers. To create end customers, it should be called in the Production environment only, even when creating Sandbox API keys. If called in the Sandbox environment, it will return a sample response, but no customer will be created and the API keys will not be valid. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The company name of the end customer being created. This will be used to display the end customer in the Plaid Dashboard. It will not be shown to end users. required, boolean Denotes whether or not the partner has completed attestation of diligence for the end customer to be created. \[string\] The products to be enabled for the end customer. If empty or `null`, this field will default to the products enabled for the reseller at the time this endpoint is called. Possible values: `assets`, `auth`, `balance`, `identity`, `income_verification`, `investments`, `investments_auth`, `liabilities`, `transactions`, `employment`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights` boolean If `true`, the end customer's default Link customization will be set to match the partner's. You can always change the end customer's Link customization in the Plaid Dashboard. See the [Link Customization docs](https://plaid.com/docs/link/customization/index.html.md) for more information. If you require the ability to programmatically create end customers using multiple different Link customization profiles, contact your Plaid Account Manager for assistance. Important: Data Transparency Messaging (DTM) use cases will not be copied to the end customer's Link customization unless the **Publish changes** button is clicked after the use cases are applied. Link will not work in Production unless the end customer's DTM use cases are configured. For more details, see [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . string Base64-encoded representation of the end customer's logo. Must be a PNG of size 1024x1024 under 4MB. The logo will be shared with financial institutions and shown to the end user during Link flows. A logo is required if `create_link_customization` is `true`. If `create_link_customization` is `false` and the logo is omitted, the partner's logo will be used if one exists, otherwise a stock logo will be used. required, string The end customer's legal name. This will be shared with financial institutions as part of the OAuth registration process. It will not be shown to end users. required, string The end customer's website. required, string The name of the end customer's application. This will be shown to end users when they go through the Plaid Link flow. The application name must be unique and cannot match the name of another application already registered with Plaid. object The technical contact for the end customer. Defaults to partner's technical contact if omitted. string string string object The billing contact for the end customer. Defaults to partner's billing contact if omitted. string string string object This information is public. Users of your app will see this information when managing connections between your app and their bank accounts in Plaid Portal. Defaults to partner's customer support info if omitted. This field is mandatory for partners whose Plaid accounts were created after November 26, 2024 and will be mandatory for all partners by the 1033 compliance deadline. string This field is mandatory for partners whose Plaid accounts were created after November 26, 2024 and will be mandatory for all partners by the 1033 compliance deadline. string string string required, object The end customer's address. string string string string string ISO-3166-1 alpha-2 country code standard. required, boolean Denotes whether the partner has forwarded the Plaid bank addendum to the end customer. object Assets under management for the given end customer. Required for end customers with monthly service commitments. required, number required, string \[string\] A list of URIs indicating the destination(s) where a user can be forwarded after completing the Link flow; used to support OAuth authentication flows when launching Link in the browser or another app. URIs should not contain any query parameters. When used in Production, URIs must use https. To modify redirect URIs for an end customer after creating them, go to the end customer's [API page](https://dashboard.plaid.com/team/api) in the Dashboard. string The unique identifier assigned to a financial institution by regulatory authorities, if applicable. For banks, this is the FDIC Certificate Number. For credit unions, this is the Credit Union Charter Number. ```node const request: PartnerCustomerCreateRequest = { address: { city: city, country_code: countryCode, postal_code: postalCode, region: region, street: street, }, application_name: applicationName, billing_contact: { email: billingEmail, given_name: billingGivenName, family_name: billingFamilyName, }, customer_support_info: { email: supportEmail, phone_number: supportPhoneNumber, contact_url: supportContactUrl, link_update_url: linkUpdateUrl, }, company_name: companyName, is_bank_addendum_completed: true, is_diligence_attested: true, legal_entity_name: legalEntityName, products: products, technical_contact: { email: technicalEmail, given_name: technicalGivenName, family_name: technicalFamilyName, }, website: website, }; try { const response = await plaidClient.partnerCustomerCreate(request); const endCustomer = response.data.end_customer; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/partner/customer/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "address": { "city": String, "country_code": String, "postal_code": String, "region": String, "street": String }, "application_name": String, "billing_contact": { "email": String, "given_name": String, "family_name": String }, "customer_support_info": { "email": String, "phone_number": String, "contact_url": String, "link_update_url": String }, "company_name": String, "is_bank_addendum_completed": Boolean, "is_diligence_attested": Boolean, "legal_entity_name": String, "products": [String], "technical_contact": { "email": String, "given_name": String, "family_name": String }, "website": String }' ``` ```ruby request = Plaid::PartnerCustomerCreateRequest.new( { address: { city: city, country_code: country_code, postal_code: postal_code, region: region, street: street }, application_name: application_name, billing_contact: { email: billing_email, given_name: billing_given_name, family_name: billing_family_name }, customer_support_info: { email: support_email, phone_number: support_phone_number, contact_url: support_contact_url, link_update_url: link_update_url }, company_name: company_name, is_bank_addendum_completed: true, is_diligence_attested: true, legal_entity_name: legal_entity_name, products: products, technical_contact: { email: technical_email, given_name: technical_given_name, family_name: technical_family_name }, website: website } ) response = client.partner_customer_create(request) end_customer = response.end_customer ``` ```java PartnerCustomerCreateRequest request = new PartnerCustomerCreateRequest() .address(address) // String .applicationName(applicationName) // String .billingContact(billingContact) // PartnerEndCustomerBillingContact .customerSupportInfo(customerSupportInfo) // PartnerEndCustomerCustomerSupportInfo .companyName(companyName) // String .isBankAddendumCompleted(true) .isDiligenceAttested(true) .legalEntityName(legalEntityName) // String .products(products) // List .technicalContact(technicalContact) // PartnerEndCustomerTechnicalContact .website(website) // String Response response = client() .partnerCustomerCreate(request) .execute(); EndCustomer endCustomer = response.body().getEndCustomer(); ``` ```python request = PartnerCustomerCreateRequest( address=address, # PartnerEndCustomerAddress application_name=application_name, # str billing_contact=billing_contact, # PartnerEndCustomerBillingContact customer_support_info=customer_support_info, # PartnerEndCustomerCustomerSupportInfo company_name=company_name, # str is_bank_addendum_completed=True, is_diligence_attested=True, legal_entity_name=legal_entity_name, # str products=products, # [Products] technical_contact=technical_contact, # PartnerEndCustomerTechnicalContact website=website #str ) response = client.partner_customer_create(request) end_customer = response['end_customer'] ``` ```go request := plaid.NewPartnerCustomerCreateRequest( companyName, // string isDiligenceAttested, // boolean products, // []string{} legalEntityName, // string website, // string applicationName, // string technicalContact, // PartnerEndCustomerTechnicalContact{} billingContact, // PartnerEndCustomerBillingContact{} customerSupportInfo, // PartnerEndCustomerCustomerSupportInfo{} address, // string isBankAddendumCompleted, // boolean ) resp, _, err := client.PlaidApi.PartnerCustomerCreate(ctx).PartnerCustomerCreateRequest(*request).Execute() if err != nil { // handle error } ``` #### Response fields  object The details for the newly created end customer, including secrets for non-Production environments. string The `client_id` of the end customer. string The company name associated with the end customer. string The status of the given end customer. `UNDER_REVIEW`: The end customer has been created and enabled in the Sandbox environment. The end customer must be manually reviewed by the Plaid team before it can be enabled in Production, at which point its status will automatically transition to `PENDING_ENABLEMENT` or `DENIED`. `PENDING_ENABLEMENT`: The end customer is ready to be fully enabled in the Production environment. Call the `/partner/customer/enable` endpoint to enable the end customer in full Production. `ACTIVE`: The end customer has been fully enabled in all environments. `DENIED`: The end customer has been created and enabled in the Sandbox environment, but it did not pass review by the Plaid team and therefore cannot be enabled for Production access. Talk to your Account Manager for more information. Possible values: `UNDER_REVIEW`, `PENDING_ENABLEMENT`, `ACTIVE`, `DENIED` object The secrets for the newly created end customer. string The end customer's secret key for the Sandbox environment. string The end customer's secret key for the Production environment. The end customer will be provided with a limited number of credits to test in the Production environment before full enablement. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "end_customer": { "client_id": "7f57eb3d2a9j6480121fx361", "company_name": "Plaid", "status": "ACTIVE", "secrets": { "sandbox": "b60b5201d006ca5a7081d27c824d77", "production": "79g03eoofwl8240v776r2h667442119" } }, "request_id": "4zlKapIkTm8p5KM" } ``` \=\*=\*=\*= #### /partner/customer/get  #### Returns a Plaid reseller's end customer.  The [/partner/customer/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomerget) endpoint is used by reseller partners to retrieve data about a single end customer. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string ```node const request: PartnerCustomerGetRequest = { end_customer_client_id: clientId, }; try { const response = await plaidClient.partnerCustomerGet(request); const endCustomer = response.data.end_customer; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/partner/customer/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "end_customer_client_id": String, }' ``` ```ruby request = Plaid::PartnerCustomerGetRequest.new( { end_customer_client_id: client_id } ) response = client.partner_customer_get(request) end_customer = response.end_customer ``` ```java PartnerCustomerGetRequest request = new PartnerCustomerGetRequest() .endCustomerClientId(clientId); Response response = client() .partnerCustomerGet(request) .execute(); EndCustomer endCustomer = response.body().getEndCustomer(); ``` ```python request = PartnerCustomerGetRequest( end_customer_client_id=client_id, ) response = client.partner_customer_get(request) end_customer = response['end_customer'] ``` ```go request := plaid.NewPartnerCustomerGetRequest(clientID) resp, _, err := client.PlaidApi.PartnerCustomerGet(ctx).PartnerCustomerGetRequest(*request).Execute() if err != nil { // handle error } ``` #### Response fields  object The details for an end customer. string The `client_id` of the end customer. string The company name associated with the end customer. string The status of the given end customer. `UNDER_REVIEW`: The end customer has been created and enabled in the Sandbox environment. The end customer must be manually reviewed by the Plaid team before it can be enabled in Production, at which point its status will automatically transition to `PENDING_ENABLEMENT` or `DENIED`. `PENDING_ENABLEMENT`: The end customer is ready to be fully enabled in the Production environment. Call the `/partner/customer/enable` endpoint to enable the end customer in full Production. `ACTIVE`: The end customer has been fully enabled in all environments. `DENIED`: The end customer has been created and enabled in the Sandbox environment, but it did not pass review by the Plaid team and therefore cannot be enabled for Production access. Talk to your Account Manager for more information. Possible values: `UNDER_REVIEW`, `PENDING_ENABLEMENT`, `ACTIVE`, `DENIED` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "end_customer": { "client_id": "7f57eb3d2a9j6480121fx361", "company_name": "Plaid", "status": "ACTIVE" }, "request_id": "4zlKapIkTm8p5KM" } ``` \=\*=\*=\*= #### /partner/customer/oauth\_institutions/get  #### Returns OAuth-institution registration information for a given end customer.  The [/partner/customer/oauth\_institutions/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomeroauth_institutionsget) endpoint is used by reseller partners to retrieve OAuth-institution registration information about a single end customer. To learn how to set up a webhook to listen to status update events, visit the [reseller documentation](https://plaid.com/docs/account/resellers/index.html.md#enabling-end-customers) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string ```node const request: PartnerCustomerOAuthInstitutionsGetRequest = { end_customer_client_id: clientId, }; try { const response = await plaidClient.partnerCustomerOAuthInstitutionsGet( request, ); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/partner/customer/oauth_institutions/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "end_customer_client_id": String, }' ``` ```ruby request = Plaid::PartnerCustomerOAuthInstitutionsGetRequest.new( { end_customer_client_id: client_id } ) response = client.partner_customer_oauth_institutions_get(request) ``` ```java PartnerCustomerOAuthInstitutionsGetRequest request = new PartnerCustomerOAuthInstitutionsGetRequest() .endCustomerClientId(clientId); Response response = client() .partnerCustomerOAuthInstitutionsGet(request) .execute(); ``` ```python request = PartnerCustomerOAuthInstitutionsGetRequest( end_customer_client_id=client_id, ) response = client.partner_customer_oauth_institutions_get(request) ``` ```go request := plaid.NewPartnerCustomerOAuthInstitutionsGetRequest(clientID) resp, _, err := client.PlaidApi.PartnerCustomerOAuthInstitutionsGet(ctx).PartnerCustomerOAuthInstitutionsGetRequest(*request).Execute() ``` #### Response fields  string The status of the addendum to the Plaid MSA ("flowdown") for the end customer. Possible values: `NOT_STARTED`, `IN_REVIEW`, `NEGOTIATION`, `COMPLETE` string The status of the end customer's security questionnaire. Possible values: `NOT_STARTED`, `RECEIVED`, `COMPLETE` \[object\] The OAuth institutions with which the end customer's application is being registered. string string object Registration statuses by environment. string The registration status for the end customer's application. Possible values: `NOT_STARTED`, `PROCESSING`, `APPROVED`, `ENABLED`, `ATTENTION_REQUIRED` string The registration status for the end customer's application. Possible values: `NOT_STARTED`, `PROCESSING`, `APPROVED`, `ENABLED`, `ATTENTION_REQUIRED` nullable, string The date on which the end customer's application was approved by the institution, or an empty string if their application has not yet been approved. nullable, string The date on which non-OAuth Item adds will no longer be supported for this institution, or an empty string if no such date has been set by the institution. \[object\] The errors encountered while registering the end customer's application with the institutions. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "flowdown_status": "COMPLETE", "questionnaire_status": "COMPLETE", "institutions": [ { "name": "Chase", "institution_id": "ins_56", "environments": { "production": "PROCESSING" }, "production_enablement_date": null, "classic_disablement_date": "2022-06-30" }, { "name": "Capital One", "institution_id": "ins_128026", "environments": { "production": "ENABLED" }, "production_enablement_date": "2022-12-19", "classic_disablement_date": null }, { "name": "Bank of America", "institution_id": "ins_1", "environments": { "production": "ATTENTION_REQUIRED" }, "production_enablement_date": null, "classic_disablement_date": null, "errors": [ { "error_type": "PARTNER_ERROR", "error_code": "OAUTH_REGISTRATION_ERROR", "error_message": "Application logo is required", "display_message": null, "request_id": "4zlKapIkTm8p5KM" } ] } ], "request_id": "4zlKapIkTm8p5KM" } ``` \=\*=\*=\*= #### /partner/customer/enable  #### Enables a Plaid reseller's end customer in the Production environment.  The [/partner/customer/enable](https://plaid.com/docs/api/partner/index.html.md#partnercustomerenable) endpoint is used by reseller partners to enable an end customer in the full Production environment. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string ```node const request: PartnerCustomerEnableRequest = { end_customer_client_id: clientId, }; try { const response = await plaidClient.partnerCustomerEnable(request); const productionSecret = response.data.production_secret; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/partner/customer/enable \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "end_customer_client_id": String, }' ``` ```ruby request = Plaid::PartnerCustomerEnableRequest.new( { end_customer_client_id: client_id } ) response = client.partner_customer_enable(request) production_secret = response.production_secret ``` ```java PartnerCustomerEnableRequest request = new PartnerCustomerEnableRequest() .endCustomerClientId(clientId); Response response = client() .partnerCustomerEnable(request) .execute(); String productionSecret = response.body().getProductionSecret(); ``` ```python request = PartnerCustomerEnableRequest( end_customer_client_id=client_id, ) response = client.partner_customer_enable(request) production_secret = response['production_secret'] ``` ```go request := plaid.NewPartnerCustomerEnableRequest(clientID) resp, _, err := client.PlaidApi.PartnerCustomerEnable(ctx).PartnerCustomerEnableRequest(*request).Execute() ``` #### Response fields  string The end customer's secret key for the Production environment. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "production_secret": "79g03eoofwl8240v776r2h667442119", "request_id": "4zlKapIkTm8p5KM" } ``` \=\*=\*=\*= #### /partner/customer/remove  #### Removes a Plaid reseller's end customer.  The [/partner/customer/remove](https://plaid.com/docs/api/partner/index.html.md#partnercustomerremove) endpoint is used by reseller partners to remove an end customer. Removing an end customer will remove it from view in the Plaid Dashboard and deactivate its API keys. This endpoint can only be used to remove an end customer that has not yet been enabled in full Production. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The `client_id` of the end customer to be removed. ```node const request: PartnerCustomerRemoveRequest = { end_customer_client_id: clientId, }; try { const response = await plaidClient.partnerCustomerRemove(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/partner/customer/remove \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "end_customer_client_id": String, }' ``` ```ruby request = Plaid::PartnerCustomerRemoveRequest.new( { end_customer_client_id: client_id } ) response = client.partner_customer_remove(request) ``` ```java PartnerCustomerRemoveRequest request = new PartnerCustomerRemoveRequest() .endCustomerClientId(clientId); Response response = client() .partnerCustomerRemove(request) .execute(); ``` ```python request = PartnerCustomerRemoveRequest( end_customer_client_id=client_id, ) response = client.partner_customer_remove(request) ``` ```go request := plaid.NewPartnerCustomerRemoveRequest(clientID) resp, _, err := client.PlaidApi.PartnerCustomerRemove(ctx).PartnerCustomerRemoveRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "4zlKapIkTm8p5KM" } ``` ### Webhooks  \=\*=\*=\*= #### PARTNER\_END\_CUSTOMER\_OAUTH\_STATUS\_UPDATED  The webhook of type `PARTNER` and code `END_CUSTOMER_OAUTH_STATUS_UPDATED` will be fired when a partner's end customer has an update on their OAuth registration status with an institution. #### Properties  string `PARTNER` string `END_CUSTOMER_OAUTH_STATUS_UPDATED` string The client ID of the end customer string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` string The institution ID string The institution name string The OAuth status of the update Possible values: `not-started`, `processing`, `approved`, `enabled`, `attention-required` API Object ```json { "webhook_type": "PARTNER", "webhook_code": "END_CUSTOMER_OAUTH_STATUS_UPDATED", "end_customer_client_id": "634758733ebb4f00134b85ea", "environment": "production", "institution_id": "ins_127989", "institution_name": "Bank of America", "status": "attention-required" } ``` --- # API - Postman Collection | Plaid Docs Plaid Postman Collection  ========================= #### Learn more about the Plaid Postman Collection, which allows you to send API requests without code  #### Introduction  Interested in experimenting with the Plaid API without having to write a full-stack application? Plaid offers a [Postman Collection](https://github.com/plaid/plaid-postman) as a convenient tool for exploring Plaid API endpoints without writing code. The Postman Collection provides pre-formatted requests for almost all of Plaid's API endpoints that you can call from their desktop application, or a web browser. All you have to do is fill in your API keys and any arguments. To get started using the Postman collection, you will need a Plaid account with access to the Sandbox environment, an account at [Postman.com](https://www.postman.com) , and (optionally) the Postman [desktop application](https://www.postman.com/downloads/) . Once you have all the prerequisites, visit our [GitHub page](https://github.com/plaid/plaid-postman) and click the "Run in Postman" button to load up the Plaid collection of endpoints. (An image of "Postman interface showing Plaid API call setup for 'Retrieve Auth' with JSON body and response displaying account details.") --- # API - Processor partners | Plaid Docs Processor partner endpoints  ============================ #### API reference for endpoints for use by Plaid partners  Partner processor endpoints are used by Plaid partners to integrate with Plaid. Instead of using an `access_token` associated with a Plaid `Item`, these endpoints use a `processor_token` to identify a single financial account. These endpoints are used only by partners and not by developers who are using those partners' APIs. If you are a Plaid developer who would like to use a partner, see [Processor token endpoints](https://plaid.com/docs/api/processors/index.html.md) . To learn how to move money with one of our partners, see [Move money with Auth](https://plaid.com/docs/auth/partnerships/index.html.md) . | In this section | | | --- | --- | | [/processor/account/get](https://plaid.com/docs/api/processor-partners/index.html.md#processoraccountget) | Fetch Account data | | [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) | Fetch Auth data | | [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) | Fetch Balance data | | [/processor/identity/get](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentityget) | Fetch Identity data | | [/processor/identity/match](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentitymatch) | Retrieve Identity match scores | | [/processor/investments/holdings/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentsholdingsget) | Fetch Investments Holdings data | | [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) | Fetch Investments Transactions data | | [/processor/liabilities/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorliabilitiesget) | Retrieve Liabilities data | | [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) | Retrieve Signal scores | | [/processor/signal/decision/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignaldecisionreport) | Report whether you initiated an ACH transaction | | [/processor/signal/return/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalreturnreport) | Report a return for an ACH transaction | | [/processor/signal/prepare](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalprepare) | Prepare a processor token for Signal | | [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) | Set the webhook URL for a processor token | | [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) | Get transaction data or incremental transaction updates | | [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) | Fetch transaction data | | [/processor/transactions/recurring/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrecurringget) | Fetch recurring transaction data | | [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) | Refresh transaction data | | Webhooks | | | --- | --- | | [WEBHOOK\_UPDATE\_ACKNOWLEDGED](https://plaid.com/docs/api/processor-partners/index.html.md#webhook_update_acknowledged) | Item's webhook receiver endpoint has been updated | \=\*=\*=\*= #### /processor/account/get  #### Retrieve the account associated with a processor token  This endpoint returns the account associated with a given processor token. This endpoint retrieves cached information, rather than extracting fresh information from the institution. As a result, the account balance returned may not be up-to-date; for realtime balance information, use [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) instead. Note that some information is nullable. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```bash curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": "${PROCESSOR_TOKEN}" }' \ -X POST \ https://sandbox.plaid.com/processor/account/get ``` ```java ProcessorAccountGetRequest request = new ProcessorAccountGetRequest() .processorToken(processorToken) Response response = client() .processorAccountGet(request) .execute(); ``` ```ruby processor_account_get_request = Plaid::ProcessorAccountGetRequest.new( { processor_token: processor_token, } ) response = client.processor_account_get(processor_account_get_request) ``` ```python request = ProcessorAccountGetRequest( processor_token=processor_token, ) response = client.processor_account_get(request) ``` ```node try { const request: ProcessorAccountGetRequest = { processor_token: processorToken, }; const response = await plaidClient.processorAccountGet(request); } catch (error) { // handle error } ``` ```go ProcessorAccountGetResp, _, err := client.PlaidApi.ProcessorAccountGet(ctx).ProcessorAccountGetRequest( *plaid.NewProcessorAccountGetRequest(processorToken), ).Execute() ``` #### Response fields  object A single account at a financial institution. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` string The Plaid Institution ID associated with the Account. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "account": { "account_id": "QKKzevvp33HxPWpoqn6rI13BxW4awNSjnw4xv", "balances": { "available": 100, "current": 110, "limit": null, "iso_currency_code": "USD", "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Checking", "subtype": "checking", "type": "depository" }, "institution_id": "ins_109508", "request_id": "1zlMf" } ``` \=\*=\*=\*= #### /processor/auth/get  #### Retrieve Auth data  The [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) endpoint returns the bank account and bank identification number (such as the routing number, for US accounts), for a checking, savings, or cash management account that''s associated with a given `processor_token`. The endpoint also returns high-level account data and balances when available. Versioning note: API versions 2019-05-29 and earlier use a different schema for the `numbers` object returned by this endpoint. For details, see [Plaid API versioning](https://plaid.com/docs/api/versioning/index.html.md#version-2020-09-14) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` ```bash curl -X POST https://sandbox.plaid.com/processor/auth/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": String }' ``` ```node const request: ProcessorAuthGetRequest = { processor_token: processorToken, }; const response = await plaidClient.processorAuthGet(request); ``` ```go request := plaid.NewProcessorAuthGetRequest(processorToken) response, _, err := client.PlaidApi.ProcessorAuthGet(ctx).ProcessorAuthGetRequest( *request ).Execute() ``` ```ruby request = Plaid::ProcessorAuthGetRequest.new({ processor_token: processor_token }) response = client.processor_auth_get(request) ``` ```python request = ProcessorAuthGetRequest( processor_token=processor_token, ) response = client.processor_auth_get(request) ``` ```java ProcessorAuthGetRequest request = new ProcessorAuthGetRequest() .processorToken(processorToken); Response response = client() .processorAuthGet(request) .execute(); ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. object An object containing identifying numbers used for making electronic transfers to and from the `account`. The identifying number type (ACH, EFT, IBAN, or BACS) used will depend on the country of the account. An account may have more than one number type. If a particular identifying number type is not used by the `account` for which auth data has been requested, a null value will be returned. nullable, object Identifying information for transferring money to or from a US account via ACH or wire transfer. string The Plaid account ID associated with the account numbers string The ACH account number for the account. At certain institutions, including Chase, PNC, and (coming May 2025) US Bank, you will receive "tokenized" routing and account numbers, which are not the user's actual account and routing numbers. For important details on how this may impact your integration and on how to avoid fraud, user confusion, and ACH returns, see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) . boolean Indicates whether the account number is tokenized by the institution. For important details on how tokenized account numbers may impact your integration, see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) . string The ACH routing number for the account. This may be a tokenized routing number. For more information, see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) . nullable, string The wire transfer routing number for the account. This field is only populated if the institution is known to use a separate wire transfer routing number. Many institutions do not have a separate wire routing number and use the ACH routing number for wires instead. It is recommended to have the end user manually confirm their wire routing number before sending any wires to their account, especially if this field is `null`. nullable, object Identifying information for transferring money to or from a Canadian bank account via EFT. string The Plaid account ID associated with the account numbers string The EFT account number for the account string The EFT institution number for the account string The EFT branch number for the account nullable, object Identifying information for transferring money to or from an international bank account via wire transfer. string The Plaid account ID associated with the account numbers string The International Bank Account Number (IBAN) for the account string The Bank Identifier Code (BIC) for the account nullable, object Identifying information for transferring money to or from a UK bank account via BACS. string The Plaid account ID associated with the account numbers string The BACS account number for the account string The BACS sort code for the account object A single account at a financial institution. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` Response Object ```json { "account": { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Checking", "subtype": "checking", "type": "depository" }, "numbers": { "ach": { "account": "9900009606", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "routing": "011401533", "wire_routing": "021000021" }, "eft": { "account": "111122223333", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "institution": "021", "branch": "01140" }, "international": { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "bic": "NWBKGB21", "iban": "GB29NWBK60161331926819" }, "bacs": { "account": "31926819", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "sort_code": "601613" } }, "request_id": "1zlMf" } ``` \=\*=\*=\*= #### /processor/balance/get  #### Retrieve Balance data  The [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) endpoint returns the real-time balance for each of an Item's accounts. While other endpoints may return a balance object, only [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) forces the available and current balance fields to be refreshed rather than cached. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` object Optional parameters to `/processor/balance/get`. string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the oldest acceptable balance when making a request to `/accounts/balance/get`. This field is only necessary when the institution is `ins_128026` (Capital One), _and_ one or more account types being requested is a non-depository account (such as a credit card) as Capital One does not provide real-time balance for non-depository accounts. In this case, a value must be provided or an `INVALID_REQUEST` error with the code of `INVALID_FIELD` will be returned. For all other institutions, as well as for depository accounts at Capital One (including all checking and savings accounts) this field is ignored and real-time balance information will be fetched. If this field is not ignored, and no acceptable balance is available, an `INVALID_RESULT` error with the code `LAST_UPDATED_DATETIME_OUT_OF_RANGE` will be returned. Format: `date-time` ```bash curl -X POST https://sandbox.plaid.com/processor/balance/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": String }' ``` ```node const request: ProcessorBalanceGetRequest = { processor_token: processorToken, }; const response = await plaidClient.processorBalanceGet(request); ``` ```go request := plaid.NewProcessorBalanceGetRequest(processorToken) response, _, err := client.PlaidApi.ProcessorBalanceGet(ctx).ProcessorBalanceGetRequest( *request ).Execute() ``` ```ruby request = Plaid::ProcessorBalanceGetRequest.new({ processor_token: processor_token }) response = client.processor_balance_get(request) ``` ```python request = ProcessorBalanceGetRequest( processor_token=processor_token, ) response = client.processor_balance_get(request) ``` ```java ProcessorBalanceGetRequest request = new ProcessorBalanceGetRequest() .processorToken(processorToken); Response response = client() .processorBalanceGet(request) .execute(); ``` #### Response fields  object A single account at a financial institution. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "account": { "account_id": "QKKzevvp33HxPWpoqn6rI13BxW4awNSjnw4xv", "balances": { "available": 100, "current": 110, "limit": null, "iso_currency_code": "USD", "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Checking", "subtype": "checking", "type": "depository" }, "request_id": "1zlMf" } ``` \=\*=\*=\*= #### /processor/identity/get  #### Retrieve Identity data  The [/processor/identity/get](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentityget) endpoint allows you to retrieve various account holder information on file with the financial institution, including names, emails, phone numbers, and addresses. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` ```bash curl -X POST https://sandbox.plaid.com/processor/identity/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": String }' ``` ```node const request: ProcessorIdentityGetRequest = { processor_token: processorToken, }; const response = await plaidClient.processorIdentityGet(request); ``` ```go request := plaid.NewProcessorIdentityGetRequest(processorToken) response, _, err := client.PlaidApi.ProcessorIdentityGet(ctx).ProcessorIdentityGetRequest( *request ).Execute() ``` ```ruby request = Plaid::ProcessorIdentityGetRequest.new({ processor_token: processor_token }) response = client.processor_identity_get(request) ``` ```python request = ProcessorIdentityGetRequest( processor_token=processor_token, ) response = client.processor_identity_get(request) ``` ```java ProcessorIdentityGetRequest request = new ProcessorIdentityGetRequest() .processorToken(processorToken); Response response = client() .processorIdentityGet(request) .execute(); ``` #### Response fields  object Identity information about an account string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution; detecting whether the linked account is a business account is not currently supported. Multiple owners on a single account will be represented in the same `owner` object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the `owners` object is not returned, and instead identity information is returned in the top level `identity` object. For more details, see [Plaid API versioning](https://plaid.com/docs/api/versioning/index.html.md#version-2019-05-29) \[string\] A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's `names` array. \[object\] A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The phone number. boolean When `true`, identifies the phone number as the primary number on an account. string The type of phone number. Possible values: `home`, `work`, `office`, `mobile`, `mobile1`, `other` \[object\] A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The email address. boolean When `true`, identifies the email address as the primary email on an account. string The type of email account as described by the financial institution. Possible values: `primary`, `secondary`, `other` \[object\] Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. object Data about the components comprising an address. nullable, string The full city name nullable, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code boolean When `true`, identifies the address as the primary address on an account. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "account": { "account_id": "XMGPJy4q1gsQoKd5z9R3tK8kJ9EWL8SdkgKMq", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "postal_code": "93405-2255", "region": "CA", "street": "2493 Leisure Lane" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholder1@example.com", "primary": false, "type": "secondary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "2025550123", "primary": false, "type": "home" }, { "data": "1112224444", "primary": false, "type": "work" }, { "data": "1112225555", "primary": false, "type": "mobile1" } ] } ], "subtype": "checking", "type": "depository" }, "request_id": "eOPkBl6t33veI2J" } ``` \=\*=\*=\*= #### /processor/identity/match  #### Retrieve identity match score  The [/processor/identity/match](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentitymatch) endpoint generates a match score, which indicates how well the provided identity data matches the identity information on file with the account holder's financial institution. Fields within the `balances` object will always be null when retrieved by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) . Instead, use the free [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint to request balance cached data, or [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) for real-time data. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` object The user's legal name, phone number, email address and address used to perform fuzzy match. If Financial Account Matching is enabled in the Identity Verification product, leave this field empty to automatically match against PII collected from the Identity Verification checks. string The user's full legal name. string The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. string The user's email address. object Data about the components comprising an address. string The full city name string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. string The ISO 3166-1 alpha-2 country code ```bash curl -X POST https://sandbox.plaid.com/processor/identity/match \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": String }' ``` ```node const request: ProcessorIdentityMatchRequest = { processor_token: processorToken, }; const response = await plaidClient.processorIdentityMatch(request); ``` ```go request := plaid.NewProcessorIdentityMatchRequest(processorToken) response, _, err := client.PlaidApi.ProcessorIdentityMatch(ctx).ProcessorIdentityMatchRequest( *request ).Execute() ``` ```ruby request = Plaid::ProcessorIdentityMatchRequest.new({ processor_token: processor_token }) response = client.processor_identity_match(request) ``` ```python request = ProcessorIdentityMatchRequest( processor_token=processor_token, ) response = client.processor_identity_match(request) ``` ```java ProcessorIdentityMatchRequest request = new ProcessorIdentityMatchRequest() .processorToken(processorToken); Response response = client() .processorIdentityMatch(request) .execute(); ``` #### Response fields  object Identity match scores for an account string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` nullable, object Score found by matching name provided by the API with the name on the account at the financial institution. If the account contains multiple owners, the maximum match score is filled. nullable, integer Match score for name. 100 is a perfect score, 99-85 means a strong match, 84-70 is a partial match, any score less than 70 is a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the name is missing from either the API or financial institution, this is null. nullable, boolean first or last name completely matched, likely a family member nullable, boolean nickname matched, example Jennifer and Jenn. nullable, boolean Is `true` if the name on either of the names that was matched for the score contained strings indicative of a business name, such as "CORP", "LLC", "INC", or "LTD". A `true` result generally indicates that an account's name is a business name. However, a `false` result does not mean the account name is not a business name, as some businesses do not use these strings in the names used for their financial institution accounts. nullable, object Score found by matching phone number provided by the API with the phone number on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled. nullable, integer Match score for normalized phone number. 100 is a perfect match, 99-70 is a partial match (matching the same phone number with extension against one without extension, etc.), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the phone number is missing from either the API or financial institution, this is null. nullable, object Score found by matching email provided by the API with the email on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled. nullable, integer Match score for normalized email. 100 is a perfect match, 99-70 is a partial match (matching the same email with different '+' extensions), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the email is missing from either the API or financial institution, this is null. nullable, object Score found by matching address provided by the API with the address on the account at the financial institution. The score can range from 0 to 100 where 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled. nullable, integer Match score for address. 100 is a perfect match, 99-90 is a strong match, 89-70 is a partial match, anything below 70 is considered a weak match. Typically, the match threshold should be set to a score of 70 or higher. If the address is missing from either the API or financial institution, this is null. nullable, boolean postal code was provided for both and was a match string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "account": { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": null, "current": null, "iso_currency_code": null, "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "legal_name": { "score": 90, "is_nickname_match": true, "is_first_name_or_last_name_match": true, "is_business_name_detected": false }, "phone_number": { "score": 100 }, "email_address": { "score": 100 }, "address": { "score": 100, "is_postal_code_match": true }, "subtype": "checking", "type": "depository" }, "request_id": "3nARps6TOYtbACO" } ``` \=\*=\*=\*= #### /processor/investments/holdings/get  #### Retrieve Investment Holdings  This endpoint returns the stock position data of the account associated with a given processor token. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```bash curl -X POST https://sandbox.plaid.com/processor/investments/holdings/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": String }' ``` ```node const request: ProcessorInvestmentsHoldingsGetRequest = { processor_token: processorToken, }; const response = await plaidClient.processorInvestmentsHoldingsGet(request); ``` ```go request := plaid.NewProcessorInvestmentsHoldingsGetRequest(processorToken) response, _, err := client.PlaidApi.ProcessorInvestmentsHoldingsGet(ctx).ProcessorInvestmentsHoldingsGetRequest( *request ).Execute() ``` ```ruby request = Plaid::ProcessorInvestmentsHoldingsGetRequest.new({ processor_token: processor_token }) response = client.processor_investments_holdings_get(request) ``` ```python request = ProcessorInvestmentsHoldingsGetRequest( processor_token=processor_token, ) response = client.processor_investments_holdings_get(request) ``` ```java ProcessorInvestmentsHoldingsGetRequest request = new ProcessorInvestmentsHoldingsGetRequest() .processorToken(processorToken); Response response = client() .processorInvestmentsHoldingsGet(request) .execute(); ``` #### Response fields  object A single account at a financial institution, with additional investment-specific balance information. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account, including margin loan information for investment accounts. nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, number The total amount of borrowed funds in the account, as determined by the financial institution. For investment-type accounts, the margin balance is the total value of borrowed assets in the account, as presented by the institution. This is commonly referred to as margin or a loan. Format: `double` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] The holdings belonging to investment accounts associated with the Item. Details of the securities in the holdings are provided in the `securities` field. string The Plaid `account_id` associated with the holding. string The Plaid `security_id` associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The `security_id` for the same security will typically be the same across different institutions, but this is not guaranteed. The `security_id` does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. number The last price given by the institution for this security. Format: `double` nullable, string The date at which `institution_price` was current. Format: `date` nullable, string Date and time at which `institution_price` was current, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). Format: `date-time` number The value of the holding, as reported by the institution. Format: `double` nullable, number The total cost basis of the holding (e.g., the total amount spent to acquire all assets currently in the holding). Format: `double` number The total quantity of the asset held, as reported by the financial institution. If the security is an option, `quantity` will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts. Format: `double` nullable, string The ISO-4217 currency code of the holding. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the holding. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, number The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with [equities](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-type) . Format: `double` nullable, number The value of the vested holdings as reported by the institution. Format: `double` \[object\] Objects describing the securities held in the account. string A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the `security_id` is case sensitive. The `security_id` may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. nullable, string 12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . nullable, string 9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . deprecated, nullable, string (Deprecated) 7-character SEDOL, an identifier assigned to securities in the UK. nullable, string An identifier given to the security by the institution nullable, string If `institution_security_id` is present, this field indicates the Plaid `institution_id` of the institution to whom the identifier belongs. nullable, string In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security. nullable, string A descriptive name for the security, suitable for display. nullable, string The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available. nullable, boolean Indicates that a security is a highly liquid asset and can be treated like cash. nullable, string The security type of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security type. Valid security types are: `cash`: Cash, currency, and money market funds `cryptocurrency`: Digital or virtual currencies `derivative`: Options, warrants, and other derivative instruments `equity`: Domestic and foreign equities `etf`: Multi-asset exchange-traded investment funds `fixed income`: Bonds and certificates of deposit (CDs) `loan`: Loans and loan receivables `mutual fund`: Open- and closed-end vehicles pooling funds of multiple investors `other`: Unknown or other investment types nullable, string The security subtype of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security subtype. Possible values: `asset backed security`, `bill`, `bond`, `bond with warrants`, `cash`, `cash management bill`, `common stock`, `convertible bond`, `convertible equity`, `cryptocurrency`, `depositary receipt`, `depositary receipt on debt`, `etf`, `float rating note`, `fund of funds`, `hedge fund`, `limited partnership unit`, `medium term note`, `money market debt`, `mortgage backed security`, `municipal bond`, `mutual fund`, `note`, `option`, `other`, `preferred convertible`, `preferred equity`, `private equity fund`, `real estate investment trust`, `structured equity product`, `treasury inflation protected securities`, `unit`, `warrant`. nullable, number Price of the security at the close of the previous trading session. Null for non-public securities. If the security is a foreign currency this field will be updated daily and will be priced in USD. If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to `update_datetime` with the time when the price was last updated. Format: `double` nullable, string Date for which `close_price` is accurate. Always `null` if `close_price` is `null`. Format: `date` nullable, string Date and time at which `close_price` is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always `null` if `close_price` is `null`. Format: `date-time` nullable, string The ISO-4217 currency code of the price given. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the security. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The ISO-10383 Market Identifier Code of the exchange or market in which the security is being traded. nullable, string The sector classification of the security, such as Finance, Health Technology, etc. For a complete list of possible values, please refer to the ["Sectors and Industries" spreadsheet](https://docs.google.com/spreadsheets/d/1L7aXUdqLhxgM8qe7hK67qqKXiUdQqILpwZ0LpxvCVnc) . nullable, string The industry classification of the security, such as Biotechnology, Airlines, etc. For a complete list of possible values, please refer to the ["Sectors and Industries" spreadsheet](https://docs.google.com/spreadsheets/d/1L7aXUdqLhxgM8qe7hK67qqKXiUdQqILpwZ0LpxvCVnc) . nullable, string The ISO-10962 Classification of Financial Instruments Code used to classify the security based on its structure and function. nullable, object Details about the option security. For the Sandbox environment, this data is currently only available if the Item is using a [custom Sandbox user](https://plaid.com/docs/sandbox/user-custom/index.html.md) and the `ticker` field of the custom security follows the [OCC Option Symbol](https://en.wikipedia.org/wiki/Option_symbol#The_OCC_Option_Symbol) standard with no spaces. For an example of simulating this in Sandbox, see the [custom Sandbox GitHub](https://github.com/plaid/sandbox-custom-users) . string The type of this option contract. It is one of: `put`: for Put option contracts `call`: for Call option contracts string The expiration date for this option contract, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` number The strike price for this option contract, per share of security. Format: `double` string The ticker of the underlying security for this option contract. nullable, object Details about the fixed income security. nullable, object Details about a fixed income security's expected rate of return. number The fixed income security's expected rate of return. Format: `double` nullable, string The type of rate which indicates how the predicted yield was calculated. It is one of: `coupon`: the annualized interest rate for securities with a one-year term or longer, such as treasury notes and bonds. `coupon_equivalent`: the calculated equivalent for the annualized interest rate factoring in the discount rate and time to maturity, for shorter term, non-interest-bearing securities such as treasury bills. `discount`: the rate at which the present value or cost is discounted from the future value upon maturity, also known as the face value. `yield`: the total predicted rate of return factoring in both the discount rate and the coupon rate, applicable to securities such as exchange-traded bonds which can both be interest-bearing as well as sold at a discount off its face value. Possible values: `coupon`, `coupon_equivalent`, `discount`, `yield`, `null` nullable, string The maturity date for this fixed income security, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` nullable, string The issue date for this fixed income security, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` nullable, number The face value that is paid upon maturity of the fixed income security, per unit of security. Format: `double` boolean When true, this field indicates that the Item's portfolio was manually created with the Investments Fallback flow. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "account": { "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1", "balances": { "available": null, "current": 110.01, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "5555", "name": "Plaid IRA", "official_name": null, "subtype": "ira", "type": "investment" }, "holdings": [ { "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1", "cost_basis": 1, "institution_price": 1, "institution_price_as_of": "2021-04-13", "institution_price_datetime": null, "institution_value": 0.01, "iso_currency_code": "USD", "quantity": 0.01, "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1", "cost_basis": 0.01, "institution_price": 0.011, "institution_price_as_of": "2021-04-13", "institution_price_datetime": null, "institution_value": 110, "iso_currency_code": "USD", "quantity": 10000, "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null } ], "securities": [ { "close_price": 0.011, "close_price_as_of": "2021-04-13", "cusip": null, "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "name": "Nflx Feb 01'18 $355 Call", "proxy_security_id": null, "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb", "sedol": null, "ticker_symbol": "NFLX180201C00355000", "type": "derivative", "subtype": "option", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": "XNAS", "sector": "Technology Services", "industry": "Internet Software or Services", "cfi_code": "OCASPS", "option_contract": { "contract_type": "call", "expiration_date": "2018-02-01", "strike_price": 355, "underlying_security_ticker": "NFLX" }, "fixed_income": null }, { "close_price": 1, "close_price_as_of": null, "cusip": null, "institution_id": null, "institution_security_id": null, "is_cash_equivalent": true, "isin": null, "iso_currency_code": "USD", "name": "U S Dollar", "proxy_security_id": null, "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are", "sedol": null, "ticker_symbol": "USD", "type": "cash", "subtype": "cash", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": null, "sector": null, "industry": null, "cfi_code": null, "option_contract": null, "fixed_income": null } ], "request_id": "24MxmGFZz89Xg2f" } ``` \=\*=\*=\*= #### /processor/investments/transactions/get  #### Get investment transactions data  The [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) endpoint allows developers to retrieve up to 24 months of user-authorized transaction data for the investment account associated with the processor token. Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift. Due to the potentially large number of investment transactions associated with the account, results are paginated. Manipulate the count and offset parameters in conjunction with the `total_investment_transactions` response body field to fetch all available investment transactions. Note that Investments does not have a webhook to indicate when initial transaction data has loaded (unless you use the `async_update` option). Instead, if transactions data is not ready when [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) is first called, Plaid will wait for the data. For this reason, calling [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) immediately after Link may take up to one to two minutes to return. Data returned by the asynchronous investments extraction flow (when `async_update` is set to true) may not be immediately available to [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) . To be alerted when the data is ready to be fetched, listen for the `HISTORICAL_UPDATE` webhook. If no investments history is ready when [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) is called, it will return a `PRODUCT_NOT_READY` error. To receive Investments Transactions webhooks for a processor token, set its webhook URL via the [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) endpoint. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. object An optional object to filter `/investments/transactions/get` results. If provided, must be non-`null`. \[string\] An array of `account_ids` to retrieve for the Item. integer The number of transactions to fetch. Default: `100` Minimum: `1` Maximum: `500` integer The number of transactions to skip when fetching transaction history Default: `0` Minimum: `0` boolean If the Item was not initialized with the investments product via the `products`, `required_if_supported_products`, or `optional_products` array when calling `/link/token/create`, and `async_update` is set to true, the initial Investments extraction will happen asynchronously. Plaid will subsequently fire a `HISTORICAL_UPDATE` webhook when the extraction completes. When `false`, Plaid will wait to return a response until extraction completion and no `HISTORICAL_UPDATE` webhook will fire. Note that while the extraction is happening asynchronously, calls to `/investments/transactions/get` and `/investments/refresh` will return `PRODUCT_NOT_READY` errors until the extraction completes. Default: `false` required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: `date` required, string The latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: `date` ```bash curl -X POST https://sandbox.plaid.com/processor/investments/transactions/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": String }' ``` ```node const request: ProcessorInvestmentsTransactionsGetRequest = { processor_token: processorToken, }; const response = await plaidClient.processorInvestmentsTransactionsGet(request); ``` ```go request := plaid.NewProcessorInvestmentsTransactionsGetRequest(processorToken) response, _, err := client.PlaidApi.ProcessorInvestmentsTransactionsGet(ctx).ProcessorInvestmentsTransactionsGetRequest( *request ).Execute() ``` ```ruby request = Plaid::ProcessorInvestmentsTransactionsGetRequest.new({ processor_token: processor_token }) response = client.processor_investments_transactions_get(request) ``` ```python request = ProcessorInvestmentsTransactionsGetRequest( processor_token=processor_token, ) response = client.processor_investments_transactions_get(request) ``` ```java ProcessorInvestmentsTransactionsGetRequest request = new ProcessorInvestmentsTransactionsGetRequest() .processorToken(processorToken); Response response = client() .processorInvestmentsTransactionsGet(request) .execute(); ``` #### Response fields  object A single account at a financial institution, with additional investment-specific balance information. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account, including margin loan information for investment accounts. nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, number The total amount of borrowed funds in the account, as determined by the financial institution. For investment-type accounts, the margin balance is the total value of borrowed assets in the account, as presented by the institution. This is commonly referred to as margin or a loan. Format: `double` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] An array containing investment transactions from the account. Investments transactions are returned in reverse chronological order, with the most recent at the beginning of the array. The maximum number of transactions returned is determined by the `count` parameter. string The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the `investment_transaction_id` is case sensitive. string The `account_id` of the account against which this transaction posted. nullable, string The `security_id` to which this transaction is related. string The [ISO 8601](https://wikipedia.org/wiki/ISO_8601) posting date for the transaction. This is typically the settlement date. Format: `date` nullable, string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) representing when the order type was initiated. This field is returned for select financial institutions and reflects the value provided by the institution. Format: `date-time` string The institution’s description of the transaction. number The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions. Format: `double` number The complete value of the transaction. Positive values when cash is debited, e.g. purchases of stock; negative values when cash is credited, e.g. sales of stock. Treatment remains the same for cash-only movements unassociated with securities. Format: `double` number The price of the security at which this transaction occurred. Format: `double` nullable, number The combined value of all fees applied to this transaction Format: `double` string Value is one of the following: `buy`: Buying an investment `sell`: Selling an investment `cancel`: A cancellation of a pending transaction `cash`: Activity that modifies a cash position `fee`: A fee on the account `transfer`: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer For descriptions of possible transaction types and subtypes, see the [Investment transaction types schema](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Possible values: `buy`, `sell`, `cancel`, `cash`, `fee`, `transfer` string For descriptions of possible transaction types and subtypes, see the [Investment transaction types schema](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Possible values: `account fee`, `adjustment`, `assignment`, `buy`, `buy to cover`, `contribution`, `deposit`, `distribution`, `dividend`, `dividend reinvestment`, `exercise`, `expire`, `fund fee`, `interest`, `interest receivable`, `interest reinvestment`, `legal fee`, `loan payment`, `long-term capital gain`, `long-term capital gain reinvestment`, `management fee`, `margin expense`, `merger`, `miscellaneous fee`, `non-qualified dividend`, `non-resident tax`, `pending credit`, `pending debit`, `qualified dividend`, `rebalance`, `return of principal`, `request`, `sell`, `sell short`, `send`, `short-term capital gain`, `short-term capital gain reinvestment`, `spin off`, `split`, `stock distribution`, `tax`, `tax withheld`, `trade`, `transfer`, `transfer fee`, `trust fee`, `unqualified gain`, `withdrawal` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the holding. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. \[object\] All securities for which there is a corresponding transaction being fetched. string A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the `security_id` is case sensitive. The `security_id` may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. nullable, string 12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . nullable, string 9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . deprecated, nullable, string (Deprecated) 7-character SEDOL, an identifier assigned to securities in the UK. nullable, string An identifier given to the security by the institution nullable, string If `institution_security_id` is present, this field indicates the Plaid `institution_id` of the institution to whom the identifier belongs. nullable, string In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security. nullable, string A descriptive name for the security, suitable for display. nullable, string The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available. nullable, boolean Indicates that a security is a highly liquid asset and can be treated like cash. nullable, string The security type of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security type. Valid security types are: `cash`: Cash, currency, and money market funds `cryptocurrency`: Digital or virtual currencies `derivative`: Options, warrants, and other derivative instruments `equity`: Domestic and foreign equities `etf`: Multi-asset exchange-traded investment funds `fixed income`: Bonds and certificates of deposit (CDs) `loan`: Loans and loan receivables `mutual fund`: Open- and closed-end vehicles pooling funds of multiple investors `other`: Unknown or other investment types nullable, string The security subtype of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security subtype. Possible values: `asset backed security`, `bill`, `bond`, `bond with warrants`, `cash`, `cash management bill`, `common stock`, `convertible bond`, `convertible equity`, `cryptocurrency`, `depositary receipt`, `depositary receipt on debt`, `etf`, `float rating note`, `fund of funds`, `hedge fund`, `limited partnership unit`, `medium term note`, `money market debt`, `mortgage backed security`, `municipal bond`, `mutual fund`, `note`, `option`, `other`, `preferred convertible`, `preferred equity`, `private equity fund`, `real estate investment trust`, `structured equity product`, `treasury inflation protected securities`, `unit`, `warrant`. nullable, number Price of the security at the close of the previous trading session. Null for non-public securities. If the security is a foreign currency this field will be updated daily and will be priced in USD. If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to `update_datetime` with the time when the price was last updated. Format: `double` nullable, string Date for which `close_price` is accurate. Always `null` if `close_price` is `null`. Format: `date` nullable, string Date and time at which `close_price` is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always `null` if `close_price` is `null`. Format: `date-time` nullable, string The ISO-4217 currency code of the price given. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the security. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The ISO-10383 Market Identifier Code of the exchange or market in which the security is being traded. nullable, string The sector classification of the security, such as Finance, Health Technology, etc. For a complete list of possible values, please refer to the ["Sectors and Industries" spreadsheet](https://docs.google.com/spreadsheets/d/1L7aXUdqLhxgM8qe7hK67qqKXiUdQqILpwZ0LpxvCVnc) . nullable, string The industry classification of the security, such as Biotechnology, Airlines, etc. For a complete list of possible values, please refer to the ["Sectors and Industries" spreadsheet](https://docs.google.com/spreadsheets/d/1L7aXUdqLhxgM8qe7hK67qqKXiUdQqILpwZ0LpxvCVnc) . nullable, string The ISO-10962 Classification of Financial Instruments Code used to classify the security based on its structure and function. nullable, object Details about the option security. For the Sandbox environment, this data is currently only available if the Item is using a [custom Sandbox user](https://plaid.com/docs/sandbox/user-custom/index.html.md) and the `ticker` field of the custom security follows the [OCC Option Symbol](https://en.wikipedia.org/wiki/Option_symbol#The_OCC_Option_Symbol) standard with no spaces. For an example of simulating this in Sandbox, see the [custom Sandbox GitHub](https://github.com/plaid/sandbox-custom-users) . string The type of this option contract. It is one of: `put`: for Put option contracts `call`: for Call option contracts string The expiration date for this option contract, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` number The strike price for this option contract, per share of security. Format: `double` string The ticker of the underlying security for this option contract. nullable, object Details about the fixed income security. nullable, object Details about a fixed income security's expected rate of return. number The fixed income security's expected rate of return. Format: `double` nullable, string The type of rate which indicates how the predicted yield was calculated. It is one of: `coupon`: the annualized interest rate for securities with a one-year term or longer, such as treasury notes and bonds. `coupon_equivalent`: the calculated equivalent for the annualized interest rate factoring in the discount rate and time to maturity, for shorter term, non-interest-bearing securities such as treasury bills. `discount`: the rate at which the present value or cost is discounted from the future value upon maturity, also known as the face value. `yield`: the total predicted rate of return factoring in both the discount rate and the coupon rate, applicable to securities such as exchange-traded bonds which can both be interest-bearing as well as sold at a discount off its face value. Possible values: `coupon`, `coupon_equivalent`, `discount`, `yield`, `null` nullable, string The maturity date for this fixed income security, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` nullable, string The issue date for this fixed income security, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` nullable, number The face value that is paid upon maturity of the fixed income security, per unit of security. Format: `double` integer The total number of transactions available within the date range specified. If `total_investment_transactions` is larger than the size of the `transactions` array, more transactions are available and can be fetched via manipulating the `offset` parameter. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. boolean When true, this field indicates that the Item's portfolio was manually created with the Investments Fallback flow. Response Object ```json { "account": { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "balances": { "available": null, "current": 23631.9805, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "6666", "name": "Plaid 401k", "official_name": null, "subtype": "401k", "type": "investment" }, "investment_transactions": [ { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "amount": -8.72, "cancel_transaction_id": null, "date": "2020-05-29", "transaction_datetime": null, "fees": 0, "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW", "iso_currency_code": "USD", "name": "INCOME DIV DIVIDEND RECEIVED", "price": 0, "quantity": 0, "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ", "subtype": "dividend", "type": "cash", "unofficial_currency_code": null }, { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "amount": -1289.01, "cancel_transaction_id": null, "date": "2020-05-28", "transaction_datetime": "2020-05-28T15:10:09Z", "fees": 7.99, "investment_transaction_id": "pK99jB9e7mtwjA435GpVuMvmWQKVbVFLWme57", "iso_currency_code": "USD", "name": "SELL Matthews Pacific Tiger Fund Insti Class", "price": 27.53, "quantity": -47.74104242992852, "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP", "subtype": "sell", "type": "sell", "unofficial_currency_code": null } ], "request_id": "iv4q3ZlytOOthkv", "securities": [ { "close_price": 27, "close_price_as_of": null, "cusip": "577130834", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US5771308344", "iso_currency_code": "USD", "name": "Matthews Pacific Tiger Fund Insti Class", "proxy_security_id": null, "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP", "sedol": null, "ticker_symbol": "MIPTX", "type": "mutual fund", "subtype": "mutual fund", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": "XNAS", "sector": "Miscellaneous", "industry": "Investment Trusts or Mutual Funds", "cfi_code": "CIOGES", "option_contract": null, "fixed_income": null }, { "close_price": 34.73, "close_price_as_of": null, "cusip": "84470P109", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US84470P1093", "iso_currency_code": "USD", "name": "Southside Bancshares Inc.", "proxy_security_id": null, "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ", "sedol": null, "ticker_symbol": "SBSI", "type": "equity", "subtype": "common stock", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": "XNAS", "sector": "Finance", "industry": "Regional Banks", "cfi_code": "ESVUFR", "option_contract": null, "fixed_income": null } ], "total_investment_transactions": 2 } ``` \=\*=\*=\*= #### /processor/signal/evaluate  #### Evaluate a planned ACH transaction  Use [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) to evaluate a planned ACH transaction to get a return risk assessment and additional risk signals. [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) uses Rulesets that are configured on the end customer's Dashboard and can be used with either the Signal Transaction Scores product or the Balance product. Which product is used will be determined by the `ruleset_key` that you provide. Note that only customer-configured rulesets work with this endpoint; as a processor partner, you cannot create or configure your own rulesets. For more details, see [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) . Note: This request may have higher latency if Signal Transaction Scores is being added to an existing Item for the first time, or when using a Balance-only ruleset. This is because Plaid must communicate directly with the institution to request data. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` required, string The unique ID that you would like to use to refer to this transaction. For your convenience mapping your internal data, you could use your internal ID/identifier for this transaction. The max length for this field is 36 characters. Min length: `1` Max length: `36` required, number The transaction amount, in USD (e.g. `102.05`) Format: `double` boolean `true` if the end user is present while initiating the ACH transfer and the endpoint is being called; `false` otherwise (for example, when the ACH transfer is scheduled and the end user is not present, or you call this endpoint after the ACH transfer but before submitting the Nacha file for ACH processing). string A unique ID that identifies the end user in your system. This ID is used to correlate requests by a user with multiple Items. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. boolean **true** if the ACH transaction is a recurring transaction; **false** otherwise string The default ACH or non-ACH payment method to complete the transaction. `SAME_DAY_ACH`: Same Day ACH by Nacha. The debit transaction is processed and settled on the same day. `STANDARD_ACH`: standard ACH by Nacha. `MULTIPLE_PAYMENT_METHODS`: if there is no default debit rail or there are multiple payment methods. Possible values: `SAME_DAY_ACH`, `STANDARD_ACH`, `MULTIPLE_PAYMENT_METHODS` object Details about the end user initiating the transaction (i.e., the account holder). These fields are optional, but strongly recommended to increase the accuracy of results when using Signal Transaction Scores. When using a Balance-only ruleset, if the Signal Addendum has been signed, these fields are ignored; if the Addendum has not been signed, using these fields will result in an error. object The user's legal name string The user's name prefix (e.g. "Mr.") string The user's given name. If the user has a one-word name, it should be provided in this field. string The user's middle name string The user's family name / surname string The user's name suffix (e.g. "II") string The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567" string The user's email address. object Data about the components comprising an address. string The full city name string The region or state Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` string The postal code string The ISO 3166-1 alpha-2 country code object Details about the end user's device. These fields are optional, but strongly recommended to increase the accuracy of results when using Signal Transaction Scores. When using a Balance-only Ruleset, these fields are ignored if the Signal Addendum has been signed; if it has not been signed, using these fields will result in an error. string The IP address of the device that initiated the transaction string The user agent of the device that initiated the transaction (e.g. "Mozilla/5.0") string The key of the ruleset to use for this transaction. You can configure a ruleset using the Plaid Dashboard, under [Signal->Rules](https://dashboard.plaid.com/signal/risk-profiles) . If not provided, for customers who began using Signal Transaction Scores before October 15, 2025, by default, no ruleset will be used; for customers who began using Signal Transaction Scores after that date, or for Balance customers, the `default` ruleset will be used. For more details, or to opt out of using a ruleset, see [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) . ```node const eval_request = { processor_token: 'processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', client_transaction_id: 'txn12345', amount: 123.45, client_user_id: 'user1234', user: { name: { prefix: 'Ms.', given_name: 'Jane', middle_name: 'Leah', family_name: 'Doe', suffix: 'Jr.', }, phone_number: '+14152223333', email_address: 'jane.doe@example.com', address: { street: '2493 Leisure Lane', city: 'San Matias', region: 'CA', postal_code: '93405-2255', country: 'US', }, }, device: { ip_address: '198.30.2.2', user_agent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1', }, user_present: true, }; try { const eval_response = await plaidClient.processorSignalEvaluate(eval_request); const core_attributes = eval_response.data.core_attributes; const scores = eval_response.data.scores; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/processor/signal/evaluate \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": "processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "client_transaction_id": "txn12345", "amount": 123.45, "client_user_id": "user1234", "user": { "name": { "prefix": "Ms.", "given_name": "Jane", "middle_name": "Leah", "family_name": "Doe", "suffix": "Jr." }, "phone_number": "+14152223333", "email_address": "jane.doe@example.com", "address": { "street": "2493 Leisure Lane", "city": "San Matias", "region": "CA", "postal_code": "93405-2255", "country": "US" } }, "device": { "ip_address": "198.30.2.2", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1" }, "user_present": true }' ``` ```ruby signalUser = Plaid::SignalUser.new( { name: Plaid::SignalPersonName.new( { prefix: 'Ms.', given_name: 'Jane', middle_name: 'Leah', family_name: 'Doe', suffix: 'Jr.' } ), phone_number: '+14152223333', email_address: 'jane.doe@example.com', address: Plaid::SignalAddressData.new( { city: 'San Matias', region: 'CA', street: '2493 Leisure Lane', postal_code: '93405-2255', country: 'US' } ) } ) signalDevice = Plaid::SignalDevice.new( { ip_address: '198.30.2.2', user_agent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1' } ) request = Plaid::ProcessorSignalEvaluateRequest.new( { processor_token: processor_token, client_transaction_id: 'txn12345', amount: 123.45, client_user_id: 'user1234', user: signalUser, device: signalDevice, user_present: true } ) response = client.processor_signal_evaluate(request) scores = response.scores core_attributes = response.core_attributes ``` ```java SignalPersonName signalPersonName = new SignalPersonName() .prefix("Ms.") .givenName("Jane") .middleName("Leah") .familyName("Doe") .suffix("Jr."); SignalAddressData signalAddressData = new SignalAddressData() .street("2493 Leisure Lane") .city("San Matias") .region("CA") .postalCode("93405-2255") .country("US"); SignalDevice signalDevice = new SignalDevice() .ipAddress("198.30.2.2") .userAgent("Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1"); SignalUser signalUser = new SignalUser() .name(signalPersonName) .phoneNumber("+14152223333") .emailAddress("jane.doe@example.com") .address(signalAddressData); ProcessorSignalEvaluateRequest request = new ProcessorSignalEvaluateRequest() .processorToken("processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175") .clientTransactionId("txn12345") .amount(123.45) .user(signalUser) .device(signalDevice) .userPresent(true); Response response = plaidClient() .processorSignalEvaluate(request) .execute(); SignalScores scores = response.body().getScores(); SignalEvaluateCoreAttributes coreAttributes = response.body().getCoreAttributes(); ``` ```python request = ProcessorSignalEvaluateRequest( processor_token="processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", client_transaction_id="txn123", amount=123.45, client_user_id="user1234", user=SignalUser( name=SignalPersonName( prefix="Ms.", given_name="Jane", middle_name="Leah", family_name="Doe", suffix="Jr.", ), phone_number="+14152223333", email_address="jane.doe@example.com", address=SignalAddressData( street="2493 Leisure Lane", city="San Matias", region="CA", postal_code="93405-2255", country="US" ) ), device=SignalDevice( ip_address="198.30.2.2", user_agent="Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1" ), user_present=True, ) response = client.processor_signal_evaluate(request) core_attributes = response['core_attributes'] scores = response['scores'] ``` ```go request := plaid.NewProcessorSignalEvaluateRequest( "processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "txn12345", 123.45, ) request.SetClientUserId("user1234") signalName := plaid.NewSignalPersonName() signalName.SetPrefix("Ms.") signalName.SetGivenName("Jane") signalName.SetMiddleName("Leah") signalName.SetFamilyName("Doe") signalName.SetSuffix("Jr.") phoneNumber := "+14152223333" emailAddress := "jane.doe@example.com" address := plaid.NewSignalAddressData() address.SetCity("San Matias") address.SetRegion("CA") address.SetStreet("2493 Leisure Lane") address.SetPostalCode("93405-2255") address.SetCountry("US") request.SetUser(plaid.SignalUser { Name: *plaid.NewNullableSignalPersonName(signalName), PhoneNumber: *plaid.NewNullableString(&phoneNumber), EmailAddress: *plaid.NewNullableString(&emailAddress), Address: *plaid.NewNullableSignalAddressData(address), }, ) device := plaid.NewSignalDevice() device.SetIpAddress("198.30.2.2") device.SetUserAgent("Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1") request.SetDevice(*device) request.SetUserPresent(true) response, _, err := client.PlaidApi.ProcessorSignalEvaluate(ctx).ProcessorSignalEvaluateRequest(*request).Execute() scores := response.GetScores() coreAttributes := response.GetCoreAttributes() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. nullable, object Risk scoring details broken down by risk category. When using a Balance-only ruleset, this object will not be returned. object The object contains a risk score and a risk tier that evaluate the transaction return risk of an unauthorized debit. Common return codes in this category include: "R05", "R07", "R10", "R11", "R29". These returns typically have a return time frame of up to 60 calendar days. During this period, the customer of financial institutions can dispute a transaction as unauthorized. integer A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood. Minimum: `1` Maximum: `99` object The object contains a risk score and a risk tier that evaluate the transaction return risk because an account is overdrawn or because an ineligible account is used. Common return codes in this category include: "R01", "R02", "R03", "R04", "R06", "R08", "R09", "R13", "R16", "R17", "R20", "R23". These returns have a turnaround time of 2 banking days. integer A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood. Minimum: `1` Maximum: `99` object The core attributes object contains additional data that can be used to assess the ACH return risk. If using a Balance-only ruleset, only `available_balance` and `current_balance` will be returned as core attributes. If using a Signal Transaction Scores ruleset, over 80 core attributes will be returned. Examples of attributes include: `available_balance` and `current_balance`: The balance in the ACH transaction funding account `days_since_first_plaid_connection`: The number of days since the first time the Item was connected to an application via Plaid `plaid_connections_count_7d`: The number of times the Item has been connected to applications via Plaid over the past 7 days `plaid_connections_count_30d`: The number of times the Item has been connected to applications via Plaid over the past 30 days `total_plaid_connections_count`: The number of times the Item has been connected to applications via Plaid `is_savings_or_money_market_account`: Indicates whether the ACH transaction funding account is a savings/money market account For the full list and detailed documentation of core attributes available, or to request that core attributes not be returned, contact Sales or your Plaid account manager. nullable, object Details about the transaction result after evaluation by the requested Ruleset. If a `ruleset_key` is not provided, for customers who began using Signal Transaction Scores before October 15, 2025, by default, this field will be omitted. To learn more, see [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) . string The key of the Ruleset used for this transaction. string The result of the rule that was triggered for this transaction. `ACCEPT`: Accept the transaction for processing. `REROUTE`: Reroute the transaction to a different payment method, as this transaction is too risky. `REVIEW`: Review the transaction before proceeding. Possible values: `ACCEPT`, `REROUTE`, `REVIEW` nullable, object Rules are run in numerical order. The first rule with a logic match is triggered. These are the details of that rule. string An optional message attached to the triggered rule, defined within the Dashboard, for your internal use. Useful for debugging, such as “Account appears to be closed.” string A string key, defined within the Dashboard, used to trigger programmatic behavior for a certain result. For instance, you could optionally choose to define a "3-day-hold" `custom_action_key` for an ACCEPT result. \[object\] If bank information was not available to be used in the Signal Transaction Scores model, this array contains warnings describing why bank data is missing. If you want to receive an API error instead of scores in the case of missing bank data, file a support ticket or contact your Plaid account manager. string A broad categorization of the warning. Safe for programmatic use. string The warning code identifies a specific kind of warning that pertains to the error causing bank data to be missing. Safe for programmatic use. For more details on warning codes, please refer to Plaid standard error codes documentation. If you receive the `ITEM_LOGIN_REQUIRED` warning, we recommend re-authenticating your user by implementing Link's update mode. This will guide your user to fix their credentials, allowing Plaid to start fetching data again for future requests. string A developer-friendly representation of the warning type. This may change over time and is not safe for programmatic use. Response Object ```json { "ruleset": { "result": "ACCEPT", "ruleset_key": "primary-ruleset", "triggered_rule_details": {} }, "scores": { "customer_initiated_return_risk": { "score": 9 }, "bank_initiated_return_risk": { "score": 72 } }, "core_attributes": { "available_balance": 2000, "current_balance": 2200 }, "warnings": [], "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /processor/liabilities/get  #### Retrieve Liabilities data  The [/processor/liabilities/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorliabilitiesget) endpoint returns various details about a loan or credit account. Liabilities data is available primarily for US financial institutions, with some limited coverage of Canadian institutions. Currently supported account types are account type `credit` with account subtype `credit card` or `paypal`, and account type `loan` with account subtype `student` or `mortgage`. The types of information returned by Liabilities can include balances and due dates, loan terms, and account details such as original loan amount and guarantor. Data is refreshed approximately once per day; the latest data can be retrieved by calling [/processor/liabilities/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorliabilitiesget) . Note: This request may take some time to complete if `liabilities` was not specified as an initial product when creating the processor token. This is because Plaid must communicate directly with the institution to retrieve the additional data. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` ```bash curl -X POST https://sandbox.plaid.com/processor/liabilities/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": String }' ``` ```node const request: ProcessorLiabilitiesGetRequest = { processor_token: processorToken, }; const response = await plaidClient.processorLiabilitiesGet(request); ``` ```go request := plaid.NewProcessorLiabilitiesGetRequest(processorToken) response, _, err := client.PlaidApi.ProcessorLiabilitiesGet(ctx).ProcessorLiabilitiesGetRequest( *request ).Execute() ``` ```ruby request = Plaid::ProcessorLiabilitiesGetRequest.new({ processor_token: processor_token }) response = client.processor_liabilities_get(request) ``` ```python request = ProcessorLiabilitiesGetRequest( processor_token=processor_token, ) response = client.processor_liabilities_get(request) ``` ```java ProcessorLiabilitiesGetRequest request = new ProcessorLiabilitiesGetRequest() .processorToken(processorToken); Response response = client() .processorLiabilitiesGet(request) .execute(); ``` #### Response fields  object A single account at a financial institution. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` object An object containing liability accounts nullable, \[object\] The credit accounts returned. nullable, string The ID of the account that this liability belongs to. \[object\] The various interest rates that apply to the account. APR information is not provided by all card issuers; if APR data is not available, this array will be empty. number Annual Percentage Rate applied. Format: `double` string The type of balance to which the APR applies. Possible values: `balance_transfer_apr`, `cash_apr`, `purchase_apr`, `special` nullable, number Amount of money that is subjected to the APR if a balance was carried beyond payment due date. How it is calculated can vary by card issuer. It is often calculated as an average daily balance. Format: `double` nullable, number Amount of money charged due to interest from last statement. Format: `double` nullable, boolean true if a payment is currently overdue. Availability for this field is limited. nullable, number The amount of the last payment. Format: `double` nullable, string The date of the last payment. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Availability for this field is limited. Format: `date` nullable, string The date of the last statement. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, number The total amount owed as of the last statement issued Format: `double` nullable, number The minimum payment due for the next billing cycle. Format: `double` nullable, string The due date for the next payment. The due date is `null` if a payment is not expected. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, \[object\] The mortgage accounts returned. string The ID of the account that this liability belongs to. nullable, string The account number of the loan. nullable, number The current outstanding amount charged for late payment. Format: `double` nullable, number Total amount held in escrow to pay taxes and insurance on behalf of the borrower. Format: `double` nullable, boolean Indicates whether the borrower has private mortgage insurance in effect. nullable, boolean Indicates whether the borrower will pay a penalty for early payoff of mortgage. object Object containing metadata about the interest rate for the mortgage. nullable, number Percentage value (interest rate of current mortgage, not APR) of interest payable on a loan. Format: `double` nullable, string The type of interest charged (fixed or variable). nullable, number The amount of the last payment. Format: `double` nullable, string The date of the last payment. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string Description of the type of loan, for example `conventional`, `fixed`, or `variable`. This field is provided directly from the loan servicer and does not have an enumerated set of possible values. nullable, string Full duration of mortgage as at origination (e.g. `10 year`). nullable, string Original date on which mortgage is due in full. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, number The amount of the next payment. Format: `double` nullable, string The due date for the next payment. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The date on which the loan was initially lent. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, number The original principal balance of the mortgage. Format: `double` nullable, number Amount of loan (principal + interest) past due for payment. Format: `double` object Object containing fields describing property address. nullable, string The city name. nullable, string The ISO 3166-1 alpha-2 country code. nullable, string The five or nine digit postal code. nullable, string The region or state (example "NC"). nullable, string The full street address (example "564 Main Street, Apt 15"). nullable, number The year to date (YTD) interest paid. Format: `double` nullable, number The YTD principal paid. Format: `double` nullable, \[object\] The student loan accounts returned. nullable, string The ID of the account that this liability belongs to. Each account can only contain one liability. nullable, string The account number of the loan. For some institutions, this may be a masked version of the number (e.g., the last 4 digits instead of the entire number). nullable, \[string\] The dates on which loaned funds were disbursed or will be disbursed. These are often in the past. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The date when the student loan is expected to be paid off. Availability for this field is limited. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The guarantor of the student loan. number The interest rate on the loan as a percentage. Format: `double` nullable, boolean `true` if a payment is currently overdue. Availability for this field is limited. nullable, number The amount of the last payment. Format: `double` nullable, string The date of the last payment. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, number The total amount owed as of the last statement issued Format: `double` nullable, string The date of the last statement. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The type of loan, e.g., "Consolidation Loans". object An object representing the status of the student loan nullable, string The date until which the loan will be in its current status. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The status type of the student loan Possible values: `cancelled`, `charged off`, `claim`, `consolidated`, `deferment`, `delinquent`, `discharged`, `extension`, `forbearance`, `in grace`, `in military`, `in school`, `not fully disbursed`, `other`, `paid in full`, `refunded`, `repayment`, `transferred`, `pending idr` nullable, number The minimum payment due for the next billing cycle. There are some exceptions: Some institutions require a minimum payment across all loans associated with an account number. Our API presents that same minimum payment amount on each loan. The institutions that do this are: Great Lakes ( `ins_116861`), Firstmark (`ins_116295`), Commonbond Firstmark Services (`ins_116950`), Granite State (`ins_116308`), and Oklahoma Student Loan Authority (`ins_116945`). Firstmark (`ins_116295` ) and Navient (`ins_116248`) will display as $0 if there is an autopay program in effect. Format: `double` nullable, string The due date for the next payment. The due date is `null` if a payment is not expected. A payment is not expected if `loan_status.type` is `deferment`, `in_school`, `consolidated`, `paid in full`, or `transferred`. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The date on which the loan was initially lent. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, number The original principal balance of the loan. Format: `double` nullable, number The total dollar amount of the accrued interest balance. For Sallie Mae ( `ins_116944`), this amount is included in the current balance of the loan, so this field will return as `null`. Format: `double` nullable, string The relevant account number that should be used to reference this loan for payments. In the majority of cases, `payment_reference_number` will match `account_number,` but in some institutions, such as Great Lakes (`ins_116861`), it will be different. object An object representing the repayment plan for the student loan nullable, string The description of the repayment plan as provided by the servicer. nullable, string The type of the repayment plan. Possible values: `extended graduated`, `extended standard`, `graduated`, `income-contingent repayment`, `income-based repayment`, `income-sensitive repayment`, `interest-only`, `other`, `pay as you earn`, `revised pay as you earn`, `standard`, `saving on a valuable education`, `null` nullable, string The sequence number of the student loan. Heartland ECSI (`ins_116948`) does not make this field available. object The address of the student loan servicer. This is generally the remittance address to which payments should be sent. nullable, string The full city name nullable, string The region or state Example: `"NC"` nullable, string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code nullable, string The ISO 3166-1 alpha-2 country code nullable, number The year to date (YTD) interest paid. Availability for this field is limited. Format: `double` nullable, number The year to date (YTD) principal paid. Availability for this field is limited. Format: `double` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "account": { "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "balances": { "available": null, "current": 410, "iso_currency_code": "USD", "limit": 2000, "unofficial_currency_code": null }, "mask": "3333", "name": "Plaid Credit Card", "official_name": "Plaid Diamond 12.5% APR Interest Credit Card", "subtype": "credit card", "type": "credit" }, "liabilities": { "credit": [ { "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "aprs": [ { "apr_percentage": 15.24, "apr_type": "balance_transfer_apr", "balance_subject_to_apr": 1562.32, "interest_charge_amount": 130.22 }, { "apr_percentage": 27.95, "apr_type": "cash_apr", "balance_subject_to_apr": 56.22, "interest_charge_amount": 14.81 }, { "apr_percentage": 12.5, "apr_type": "purchase_apr", "balance_subject_to_apr": 157.01, "interest_charge_amount": 25.66 }, { "apr_percentage": 0, "apr_type": "special", "balance_subject_to_apr": 1000, "interest_charge_amount": 0 } ], "is_overdue": false, "last_payment_amount": 168.25, "last_payment_date": "2019-05-22", "last_statement_issue_date": "2019-05-28", "last_statement_balance": 1708.77, "minimum_payment_amount": 20, "next_payment_due_date": "2020-05-28" } ], "mortgage": [], "student": [] }, "request_id": "dTnnm60WgKGLnKL" } ``` \=\*=\*=\*= #### /processor/signal/decision/report  #### Report whether you initiated an ACH transaction  After you call [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) , Plaid will normally infer the outcome from your Signal Rules. However, if you are not using Signal Rules, if the Signal Rules outcome was `REVIEW`, or if you take a different action than the one determined by the Signal Rules, you will need to call [/processor/signal/decision/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignaldecisionreport) . This helps improve Signal Transaction Score accuracy for your account and is necessary for proper functioning of the rule performance and rule tuning capabilities in the Dashboard. If your effective decision changes after calling [/processor/signal/decision/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignaldecisionreport) (for example, you indicated that you accepted a transaction, but later on, your payment processor rejected it, so it was never initiated), call [/processor/signal/decision/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignaldecisionreport) again for the transaction to correct Plaid's records. If you are using Plaid Transfer as your payment processor, you also do not need to call [/processor/signal/decision/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignaldecisionreport) , as Plaid can infer outcomes from your Transfer activity. If using a Balance-only ruleset, this endpoint will not impact scores (Balance does not use scores), but is necessary to view accurate transaction outcomes and tune rule logic in the Dashboard. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` required, string Must be the same as the `client_transaction_id` supplied when calling `/processor/signal/evaluate` Min length: `1` Max length: `36` required, boolean `true` if the ACH transaction was initiated, `false` otherwise. This field must be returned as a boolean. If formatted incorrectly, this will result in an [INVALID\_FIELD](https://plaid.com/docs/errors/invalid-request/index.html.md#invalid_field) error. integer The actual number of days (hold time) since the ACH debit transaction that you wait before making funds available to your customers. The holding time could affect the ACH return rate. For example, use 0 if you make funds available to your customers instantly or the same day following the debit transaction, or 1 if you make funds available the next day following the debit initialization. Minimum: `0` string The payment decision from the risk assessment. `APPROVE`: approve the transaction without requiring further actions from your customers. For example, use this field if you are placing a standard hold for all the approved transactions before making funds available to your customers. You should also use this field if you decide to accelerate the fund availability for your customers. `REVIEW`: the transaction requires manual review `REJECT`: reject the transaction `TAKE_OTHER_RISK_MEASURES`: for example, placing a longer hold on funds than those approved transactions or introducing customer frictions such as step-up verification/authentication `NOT_EVALUATED`: if only logging the results without using them Possible values: `APPROVE`, `REVIEW`, `REJECT`, `TAKE_OTHER_RISK_MEASURES`, `NOT_EVALUATED` string The payment method to complete the transaction after the risk assessment. It may be different from the default payment method. `SAME_DAY_ACH`: Same Day ACH by Nacha. The debit transaction is processed and settled on the same day. `STANDARD_ACH`: Standard ACH by Nacha. `MULTIPLE_PAYMENT_METHODS`: if there is no default debit rail or there are multiple payment methods. Possible values: `SAME_DAY_ACH`, `STANDARD_ACH`, `MULTIPLE_PAYMENT_METHODS` number The amount (in USD) made available to your customers instantly following the debit transaction. It could be a partial amount of the requested transaction (example: 102.05). Format: `double` ```node const decision_report_request = { processor_token: 'processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', client_transaction_id: 'txn12345', initiated: true, days_funds_on_hold: 3, }; try { const decision_report_response = await plaidClient.processorSignalDecisionReport(decision_report_request); const decision_request_id = decision_report_response.data.request_id; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/processor/signal/decision/report \ -H 'content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": "processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "client_transaction_id": "txn123", "initiated": true }' ``` ```ruby request = Plaid::ProcessorSignalDecisionReportRequest.new( { processor_token: 'processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', client_transaction_id: 'txn12345', initiated: true, days_funds_on_hold: 3 } ) response = client.processor_signal_decision_report(request) request_id = response.request_id ``` ```java ProcessorSignalDecisionReportRequest request = new ProcessorSignalDecisionReportRequest() .processorToken("processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175") .clientTransactionId("txn12345") .initiated(true) .daysFundsOnHold(3); Response response = plaidClient() .processorSignalDecisionReport(request) .execute(); String requestID = response.body().getRequestId(); ``` ```python request = ProcessorSignalDecisionReportRequest( processor_token="processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", client_transaction_id="txn12345", initiated=True, days_funds_on_hold=3, ) response = client.processor_signal_decision_report(request) request_id = response['request_id'] ``` ```go request := plaid.NewProcessorSignalDecisionReportRequest( "processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "txn12345", true, ) request.SetDaysFundsOnHold(3) response, _, err := client.PlaidApi.ProcessorSignalDecisionReport(ctx).ProcessorSignalDecisionReportRequest(*request).Execute() request_id := response.GetRequestId() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /processor/signal/return/report  #### Report a return for an ACH transaction  Call the [/processor/signal/return/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalreturnreport) endpoint to report a returned transaction that was previously sent to the [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) endpoint. Your feedback will be used by the model to incorporate the latest risk trend in your portfolio. If you are using the [Plaid Transfer product](https://plaid.com/docs/transfer/index.html.md) to create transfers, it is not necessary to use this endpoint, as Plaid already knows whether the transfer was returned. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` required, string Must be the same as the `client_transaction_id` supplied when calling `/processor/signal/evaluate` Min length: `1` Max length: `36` required, string Must be a valid ACH return code (e.g. "R01") If formatted incorrectly, this will result in an [INVALID\_FIELD](https://plaid.com/docs/errors/invalid-request/index.html.md#invalid_field) error. string Date and time when you receive the returns from your payment processors, in ISO 8601 format (`YYYY-MM-DDTHH:mm:ssZ`). Format: `date-time` ```node const return_report_request = { processor_token: 'processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', client_transaction_id: 'txn12345', return_code: 'R01', }; try { const return_report_response = await plaidClient.processorSignalReturnReport( return_report_request, ); const request_id = return_report_response.data.request_id; console.log(request_id); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/processor/signal/return/report \ -H 'content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": "processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "client_transaction_id": "txn12345", "return_code": "R01" }' ``` ```ruby request = Plaid::ProcessorSignalReturnReportRequest.new( { processor_token: 'processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', client_transaction_id: 'txn12345', return_code: 'R01' } ) response = client.processor_signal_return_report(request) request_id = response.request_id ``` ```java ProcessorSignalReturnReportRequest request = new ProcessorSignalReturnReportRequest() .processorToken("processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175") .clientTransactionId("txn12345") .returnCode("R01"); Response response = client() .processorSignalReturnReport(request) .execute(); String requestId = response.body().getRequestId(); ``` ```python request = ProcessorSignalReturnReportRequest( processor_token="processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", client_transaction_id="txn12345", return_code="R01", ) response = client.processor_signal_return_report(request) request_id = response['request_id'] ``` ```go request := plaid.NewProcessorSignalReturnReportRequest( "processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "txn12345", "R01", ) response, _, err := client.PlaidApi.ProcessorSignalReturnReport(ctx).ProcessorSignalReturnReportRequest(*request).Execute() request_id := response.GetRequestId() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /processor/signal/prepare  #### Opt-in a processor token to Signal  When a processor token is not initialized with `signal`, call [/processor/signal/prepare](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalprepare) to opt-in that processor token to the data collection process, which will improve the accuracy of the Signal Transaction Score. If this endpoint is called with a processor token that is already initialized with `signal`, it will return a 200 response and will not modify the processor token. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` ```node const prepare_request = { processor_token: 'processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', }; try { const prepare_response = await plaidClient.processorSignalPrepare(prepare_request); const prepare_request_id = prepare_response.data.request_id; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/processor/signal/prepare \ -H 'content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": "processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175" }' ``` ```ruby request = Plaid::ProcessorSignalPrepareRequest.new( { processor_token: 'processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', } ) response = client.processor_signal_prepare(request) request_id = response.request_id ``` ```java ProcessorSignalPrepareRequest request = new ProcessorSignalPrepareRequest() .processorToken("processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175"); Response response = plaidClient() .processorSignalPrepare(request) .execute(); String requestID = response.body().getRequestId(); ``` ```python request = ProcessorSignalPrepareRequest( processor_token="processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", ) response = client.processor_signal_prepare(request) request_id = response['request_id'] ``` ```go request := plaid.NewProcessorSignalPrepareRequest( "processor-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", ) request.SetDaysFundsOnHold(3) response, _, err := client.PlaidApi.ProcessorSignalPrepare(ctx).ProcessorSignalPrepareRequest(*request).Execute() request_id := response.GetRequestId() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /processor/token/webhook/update  #### Update a processor token's webhook URL  This endpoint allows you, the processor, to update the webhook URL associated with a processor token. This request triggers a `WEBHOOK_UPDATE_ACKNOWLEDGED` webhook to the newly specified webhook URL. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` required, string The new webhook URL to associate with the processor token. To remove a webhook from a processor token, set to `null`. Format: `url` ```bash curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": "${PROCESSOR_TOKEN}", "webhook": "https://www.example-webhook.com" }' \ -X POST \ https://sandbox.plaid.com/processor/token/webhook/update ``` ```java ProcessorTokenWebhookUpdateRequest request = new ProcessorTokenWebhookUpdateRequest() .processorToken(processorToken) .webhook(webhook) Response response = client() .processorTokenWebhookUpdate(request) .execute(); ``` ```ruby processor_token_webhook_update_request = Plaid::ProcessorTokenWebhookUpdateRequest.new( { processor_token: processor_token, webhook: webhook, } ) response = client.processor_token_webhook_update(processor_token_webhook_update_request) ``` ```python request = ProcessorTokenWebhookUpdateRequest( processor_token=processor_token, webhook=webhook, ) response = client.processor_token_webhook_update(request) ``` ```node try { const request: ProcessorTokenWebhookUpdateRequest = { processor_token: processorToken, webhook: webhook, }; const response = await plaidClient.processorTokenWebhookUpdate(request); } catch (error) { // handle error } ``` ```go processorTokenWebhookUpdateResp, _, err := client.PlaidApi.ProcessorTokenWebhookUpdate(ctx).ProcessorTokenWebhookUpdateRequest( *plaid.NewProcessorTokenWebhookUpdateRequest(processorToken), ).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "vYK11LNTfRoAMbj" } ``` \=\*=\*=\*= #### /processor/transactions/sync  #### Get incremental transaction updates on a processor token  The [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) endpoint retrieves transactions associated with an Item and can fetch updates using a cursor to track which updates have already been seen. For important instructions on integrating with [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) , see the [Transactions integration overview](https://plaid.com/docs/transactions/index.html.md#integration-overview) . If you are migrating from an existing integration using [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) , see the [Transactions Sync migration guide](https://plaid.com/docs/transactions/sync-migration/index.html.md) . This endpoint supports `credit`, `depository`, and some `loan`\-type accounts (only those with account subtype `student`). For `investments` accounts, use [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) instead. When retrieving paginated updates, track both the `next_cursor` from the latest response and the original cursor from the first call in which `has_more` was `true`; if a call to [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) fails when retrieving a paginated update (e.g due to the [TRANSACTIONS\_SYNC\_MUTATION\_DURING\_PAGINATION](https://plaid.com/docs/errors/transactions/index.html.md#transactions_sync_mutation_during_pagination) error), the entire pagination request loop must be restarted beginning with the cursor for the first page of the update, rather than retrying only the single request that failed. If transactions data is not yet available for the Item, which can happen if the Item was not initialized with transactions during the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call or if [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) was called within a few seconds of Item creation, [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) will return empty transactions arrays. Plaid typically checks for new transactions data between one and four times per day, depending on the institution. To find out when transactions were last updated for an Item, use the [Item Debugger](https://plaid.com/docs/account/activity/index.html.md#troubleshooting-with-item-debugger) or call [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) ; the `item.status.transactions.last_successful_update` field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, use the [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) endpoint. To be alerted when new transactions are available, listen for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) webhook. To receive Transactions webhooks for a processor token, set its webhook URL via the [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) endpoint. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The cursor value represents the last update requested. Providing it will cause the response to only return changes after this update. If omitted, the entire history of updates will be returned, starting with the first-added transactions on the item. Note: The upper-bound length of this cursor is 256 characters of base64. integer The number of transaction updates to fetch. Default: `100` Minimum: `1` Maximum: `500` Exclusive min: `false` object An optional object to be used with the request. If specified, `options` must not be `null`. boolean Include the raw unparsed transaction description from the financial institution. Default: `false` string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` integer This field only applies to calls for Items where the Transactions product has not already been initialized (i.e., by specifying `transactions` in the `products`, `required_if_supported_products`, or `optional_products` array when calling `/link/token/create` or by making a previous call to `/transactions/sync` or `/transactions/get`). In those cases, the field controls the maximum number of days of transaction history that Plaid will request from the financial institution. The more transaction history is requested, the longer the historical update poll will take. If no value is specified, 90 days of history will be requested by default. In Production, if a value less than 30 is provided, a minimum of 30 days of transaction history will be requested. If you are initializing your Items with transactions during the `/link/token/create` call (e.g. by including `transactions` in the `/link/token/create` `products` array), you must use the [transactions.days\_requested](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transactions-days-requested) field in the `/link/token/create` request instead of in the `/transactions/sync` request. If the Item has already been initialized with the Transactions product, this field will have no effect. The maximum amount of transaction history to request on an Item cannot be updated if Transactions has already been added to the Item. To request older transaction history on an Item where Transactions has already been added, you must delete the Item via `/item/remove` and send the user through Link to create a new Item. Customers using [Recurring Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) should request at least 180 days of history for optimal results. Minimum: `1` Maximum: `730` Default: `90` string If provided, the returned updates and cursor will only reflect the specified account's transactions. Omitting `account_id` returns updates for all accounts under the Item. Note that specifying an `account_id` effectively creates a separate incremental update stream—and therefore a separate cursor—for that account. If multiple accounts are queried this way, you will maintain multiple cursors, one per `account_id`. If you decide to begin filtering by `account_id` after using no `account_id`, start fresh with a null cursor and maintain separate `(account_id, cursor)` pairs going forward. Do not reuse any previously saved cursors, as this can cause pagination errors or incomplete data. Note: An error will be returned if a provided `account_id` is not associated with the Item. ```node // Provide a cursor from your database if you've previously // received one for the Item. Leave null if this is your // first sync call for this Item. The first request will // return a cursor. let cursor = database.getLatestCursorOrNull(itemId); // New transaction updates since "cursor" let added: Array = []; let modified: Array = []; // Removed transaction ids let removed: Array = []; let hasMore = true; // Iterate through each page of new transaction updates for item while (hasMore) { const request: ProcessorTransactionsSyncRequest = { processor_token: processorToken, cursor: cursor, }; const response = await client.processorTransactionsSync(request); const data = response.data; // Add this page of results added = added.concat(data.added); modified = modified.concat(data.modified); removed = removed.concat(data.removed); hasMore = data.has_more; // Update cursor to the next cursor cursor = data.next_cursor; } // Persist cursor and updated data database.applyUpdates(itemId, added, modified, removed, cursor); ``` ```bash curl -X POST https://sandbox.plaid.com/processor/transactions/sync \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": String, "cursor": String, "count": 250 }' ``` ```ruby # Provide a cursor from your database if you've previously # received one for the Item. Leave null if this is your # first sync call for this item. The first request will # return a cursor. cursor = database.get_latest_cursor_or_none(item_id) # New transaction updates since "cursor" added = [] modified = [] removed = [] # Removed transaction ids has_more = true # Iterate through each page of new transaction updates for item while has_more request = Plaid::ProcessorTransactionsSyncRequest.new( { processor_token: processor_token, cursor: cursor } ) response = client.processor_transactions_sync(request) # Add this page of results added += response.added modified += response.modified removed += response.removed has_more = response.has_more # Update cursor to the next cursor cursor = response.next_cursor end # Persist cursor and updated data database.apply_updates(item_id, added, modified, removed, cursor) ``` ```java // Provide a cursor from your database if you've previously // received one for the item leave null if this is your // first sync call for this item. The first request will // return a cursor. String cursor = database.getLatestCursorOrNull(itemId); // New transaction updates since "cursor" List added = new ArrayList(); List modified = new ArrayList(); List removed = new ArrayList(); boolean hasMore = true; // Iterate through each page of new transaction updates for item while (hasMore) { ProcessorTransactionsSyncRequest request = new ProcessorTransactionsSyncRequest() .processorToken(processorToken) .cursor(cursor); response = plaidClient.processorTransactionsSync(request).execute(); // Add this page of results added.addAll(response.getAdded()); modified.addAll(response.getModified()); removed.addAll(response.getRemoved()); hasMore = response.getHasMore(); // Update cursor to the next cursor cursor = response.getNextCursor(); } // Persist cursor and updated data database.applyUpdates(itemId, added, modified, removed, cursor); ``` ```python # Provide a cursor from your database if you've previously # received one for the Item. Leave null if this is your # first sync call for this Item. The first request will # return a cursor. cursor = database.get_latest_cursor_or_none(item_id) # New transaction updates since "cursor" added = [] modified = [] removed = [] # Removed transaction ids has_more = True # Iterate through each page of new transaction updates for item while has_more: request = ProcessorTransactionsSyncRequest( processor_token=processor_token, cursor=cursor, ) response = plaid_client.processor_transactions_sync(request) # Add this page of results added.extend(response['added']) modified.extend(response['modified']) removed.extend(response['removed']) has_more = response['has_more'] # Update cursor to the next cursor cursor = response['next_cursor'] # Persist cursor and updated data database.apply_updates(item_id, added, modified, removed, cursor) ``` ```go // Provide a cursor from your database if you've previously // received one for the Item. Leave null if this is your // first sync call for this Item. The first request will // return a cursor. cursor := database.getLatestCursorOrNil(itemId) // New transaction updates since "cursor" var added []Transaction var modified []Transaction var removed []RemovedTransaction // Removed transaction ids hasMore := true // Iterate through each page of new transaction updates for item for hasMore { request := plaid.NewProcessorTransactionsSyncRequest(processorToken) if cursor != nil { request.SetCursor(*cursor) } resp, _, err := client.PlaidApi.ProcessorTransactionsSync( ctx, ).ProcessorTransactionsSyncRequest(*request).Execute() // Add this page of results added = append(added, resp.GetAdded()...) modified = append(modified, resp.GetModified()...) removed = append(removed, resp.GetRemoved()...) hasMore = resp.GetHasMore() // Update cursor to the next cursor cursor = &resp.GetNextCursor() } // Persist cursor and updated data database.applyUpdates(itemId, added, modified, removed, cursor) ``` #### Response fields  string A description of the update status for transaction pulls of an Item. This field contains the same information provided by transactions webhooks, and may be helpful for webhook troubleshooting or when recovering from missed webhooks. `TRANSACTIONS_UPDATE_STATUS_UNKNOWN`: Unable to fetch transactions update status for Item. `NOT_READY`: The Item is pending transaction pull. `INITIAL_UPDATE_COMPLETE`: Initial pull for the Item is complete, historical pull is pending. `HISTORICAL_UPDATE_COMPLETE`: Both initial and historical pull for Item are complete. Possible values: `TRANSACTIONS_UPDATE_STATUS_UNKNOWN`, `NOT_READY`, `INITIAL_UPDATE_COMPLETE`, `HISTORICAL_UPDATE_COMPLETE` nullable, object A single account at a financial institution. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] Transactions that have been added to the Item since `cursor` ordered by ascending last modified time. string The ID of the account in which this transaction occurred. number The settled value of the transaction, denominated in the transactions's currency, as stated in `iso_currency_code` or `unofficial_currency_code`. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: `double` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The check number of the transaction. This field is only populated for check transactions. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). To receive information about the date that a posted transaction was initiated, see the `authorized_date` field. Format: `date` object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. deprecated, string The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use `merchant_name` instead for the merchant name. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, this field will always appear. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The merchant name, as enriched by Plaid from the `name` field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be `null`. nullable, string The string returned by the financial institution to describe the transaction. For transactions returned by `/transactions/sync` or `/transactions/get`, this field will only be included if the client has set `options.include_original_description` to `true`. object Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be `null`. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, the `payment_meta` key will always appear, but no data elements are guaranteed. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The transaction reference number supplied by the financial institution. nullable, string The ACH PPD ID for the payer. nullable, string For transfers, the party that is receiving the transaction. nullable, string The party initiating a wire transfer. Will be `null` if the transaction is not a wire transfer. nullable, string For transfers, the party that is paying the transaction. nullable, string The type of transfer, e.g. 'ACH' nullable, string The name of the payment processor nullable, string The payer-supplied description of the transfer. boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions. nullable, string The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions. nullable, string This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. deprecated, string Please use the `payment_channel` field, `transaction_type` will be deprecated in the future. `digital:` transactions that took place online. `place:` transactions that were made at a physical location. `special:` transactions that relate to banks, e.g. fees or deposits. `unresolved:` transactions that do not fit into the other three types. Possible values: `digital`, `place`, `special`, `unresolved` nullable, string The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file. nullable, string The website associated with this transaction, if available. nullable, string The date that the transaction was authorized. For posted transactions, the `date` field will indicate the posted date, but `authorized_date` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_date`, when available, is generally preferable to use over the `date` field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). Format: `date` nullable, string Date and time when a transaction was authorized in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For posted transactions, the `datetime` field will indicate the posted date, but `authorized_datetime` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_datetime`, when available, is generally preferable to use over the `datetime` field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` nullable, string Date and time when a transaction was posted in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For the date that the transaction was initiated, rather than posted, see the `authorized_datetime` field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` string The channel used to make a payment. `online:` transactions that took place online. `in store:` transactions that were made at a physical location. `other:` transactions that relate to banks, e.g. fees or deposits. This field replaces the `transaction_type` field. Possible values: `online`, `in store`, `other` nullable, object Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the [taxonomy CSV file](https://plaid.com/documents/pfc-taxonomy-all.csv) for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the [migration guide](https://plaid.com/docs/transactions/pfc-migration/index.html.md) . string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string A description of how confident we are that the provided categories accurately describe the transaction intent. `VERY_HIGH`: We are more than 98% confident that this category reflects the intent of the transaction. `HIGH`: We are more than 90% confident that this category reflects the intent of the transaction. `MEDIUM`: We are moderately confident that this category reflects the intent of the transaction. `LOW`: This category may reflect the intent, but there may be other categories that are more accurate. `UNKNOWN`: We don’t know the confidence level for this category. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` nullable, string An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to `null`. `adjustment:` Bank adjustment `atm:` Cash deposit or withdrawal via an automated teller machine `bank charge:` Charge or fee levied by the institution `bill payment`: Payment of a bill `cash:` Cash deposit or withdrawal `cashback:` Cash withdrawal while making a debit card purchase `cheque:` Document ordering the payment of money to another person or organization `direct debit:` Automatic withdrawal of funds initiated by a third party at a regular interval `interest:` Interest earned or incurred `purchase:` Purchase made with a debit or credit card `standing order:` Payment instructed by the account holder to a third party at a regular interval `transfer:` Transfer of money between accounts Possible values: `adjustment`, `atm`, `bank charge`, `bill payment`, `cash`, `cashback`, `cheque`, `direct debit`, `interest`, `purchase`, `standing order`, `transfer`, `null` string The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file. \[object\] The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description. string The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description. nullable, string A unique, stable, Plaid-generated ID that maps to the counterparty. string The counterparty type. `merchant`: a provider of goods or services for purchase `financial_institution`: a financial entity (bank, credit union, BNPL, fintech) `payment_app`: a transfer or P2P app (e.g. Zelle) `marketplace`: a marketplace (e.g DoorDash, Google Play Store) `payment_terminal`: a point-of-sale payment terminal (e.g Square, Toast) `income_source`: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: `merchant`, `financial_institution`, `payment_app`, `marketplace`, `payment_terminal`, `income_source` nullable, string The website associated with the counterparty. nullable, string The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file. nullable, string A description of how confident we are that the provided counterparty is involved in the transaction. `VERY_HIGH`: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. `HIGH`: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. `MEDIUM`: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. `LOW`: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. `UNKNOWN`: We don’t know the confidence level for this counterparty. nullable, object Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe. nullable, object Identifying information for a UK bank account via BACS. nullable, string The BACS account number for the account. nullable, string The BACS sort code for the account. nullable, object Account numbers using the International Bank Account Number and BIC/SWIFT code format. nullable, string International Bank Account Number (IBAN). Min length: `15` Max length: `34` nullable, string Bank identifier code (BIC) for this counterparty. Min length: `8` Max length: `11` nullable, string A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store. \[object\] Transactions that have been modified on the Item since `cursor` ordered by ascending last modified time. string The ID of the account in which this transaction occurred. number The settled value of the transaction, denominated in the transactions's currency, as stated in `iso_currency_code` or `unofficial_currency_code`. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: `double` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The check number of the transaction. This field is only populated for check transactions. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). To receive information about the date that a posted transaction was initiated, see the `authorized_date` field. Format: `date` object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. deprecated, string The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use `merchant_name` instead for the merchant name. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, this field will always appear. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The merchant name, as enriched by Plaid from the `name` field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be `null`. nullable, string The string returned by the financial institution to describe the transaction. For transactions returned by `/transactions/sync` or `/transactions/get`, this field will only be included if the client has set `options.include_original_description` to `true`. object Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be `null`. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, the `payment_meta` key will always appear, but no data elements are guaranteed. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The transaction reference number supplied by the financial institution. nullable, string The ACH PPD ID for the payer. nullable, string For transfers, the party that is receiving the transaction. nullable, string The party initiating a wire transfer. Will be `null` if the transaction is not a wire transfer. nullable, string For transfers, the party that is paying the transaction. nullable, string The type of transfer, e.g. 'ACH' nullable, string The name of the payment processor nullable, string The payer-supplied description of the transfer. boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions. nullable, string The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions. nullable, string This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. deprecated, string Please use the `payment_channel` field, `transaction_type` will be deprecated in the future. `digital:` transactions that took place online. `place:` transactions that were made at a physical location. `special:` transactions that relate to banks, e.g. fees or deposits. `unresolved:` transactions that do not fit into the other three types. Possible values: `digital`, `place`, `special`, `unresolved` nullable, string The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file. nullable, string The website associated with this transaction, if available. nullable, string The date that the transaction was authorized. For posted transactions, the `date` field will indicate the posted date, but `authorized_date` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_date`, when available, is generally preferable to use over the `date` field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). Format: `date` nullable, string Date and time when a transaction was authorized in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For posted transactions, the `datetime` field will indicate the posted date, but `authorized_datetime` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_datetime`, when available, is generally preferable to use over the `datetime` field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` nullable, string Date and time when a transaction was posted in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For the date that the transaction was initiated, rather than posted, see the `authorized_datetime` field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` string The channel used to make a payment. `online:` transactions that took place online. `in store:` transactions that were made at a physical location. `other:` transactions that relate to banks, e.g. fees or deposits. This field replaces the `transaction_type` field. Possible values: `online`, `in store`, `other` nullable, object Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the [taxonomy CSV file](https://plaid.com/documents/pfc-taxonomy-all.csv) for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the [migration guide](https://plaid.com/docs/transactions/pfc-migration/index.html.md) . string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string A description of how confident we are that the provided categories accurately describe the transaction intent. `VERY_HIGH`: We are more than 98% confident that this category reflects the intent of the transaction. `HIGH`: We are more than 90% confident that this category reflects the intent of the transaction. `MEDIUM`: We are moderately confident that this category reflects the intent of the transaction. `LOW`: This category may reflect the intent, but there may be other categories that are more accurate. `UNKNOWN`: We don’t know the confidence level for this category. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` nullable, string An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to `null`. `adjustment:` Bank adjustment `atm:` Cash deposit or withdrawal via an automated teller machine `bank charge:` Charge or fee levied by the institution `bill payment`: Payment of a bill `cash:` Cash deposit or withdrawal `cashback:` Cash withdrawal while making a debit card purchase `cheque:` Document ordering the payment of money to another person or organization `direct debit:` Automatic withdrawal of funds initiated by a third party at a regular interval `interest:` Interest earned or incurred `purchase:` Purchase made with a debit or credit card `standing order:` Payment instructed by the account holder to a third party at a regular interval `transfer:` Transfer of money between accounts Possible values: `adjustment`, `atm`, `bank charge`, `bill payment`, `cash`, `cashback`, `cheque`, `direct debit`, `interest`, `purchase`, `standing order`, `transfer`, `null` string The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file. \[object\] The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description. string The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description. nullable, string A unique, stable, Plaid-generated ID that maps to the counterparty. string The counterparty type. `merchant`: a provider of goods or services for purchase `financial_institution`: a financial entity (bank, credit union, BNPL, fintech) `payment_app`: a transfer or P2P app (e.g. Zelle) `marketplace`: a marketplace (e.g DoorDash, Google Play Store) `payment_terminal`: a point-of-sale payment terminal (e.g Square, Toast) `income_source`: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: `merchant`, `financial_institution`, `payment_app`, `marketplace`, `payment_terminal`, `income_source` nullable, string The website associated with the counterparty. nullable, string The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file. nullable, string A description of how confident we are that the provided counterparty is involved in the transaction. `VERY_HIGH`: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. `HIGH`: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. `MEDIUM`: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. `LOW`: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. `UNKNOWN`: We don’t know the confidence level for this counterparty. nullable, object Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe. nullable, object Identifying information for a UK bank account via BACS. nullable, string The BACS account number for the account. nullable, string The BACS sort code for the account. nullable, object Account numbers using the International Bank Account Number and BIC/SWIFT code format. nullable, string International Bank Account Number (IBAN). Min length: `15` Max length: `34` nullable, string Bank identifier code (BIC) for this counterparty. Min length: `8` Max length: `11` nullable, string A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store. \[object\] Transactions that have been removed from the Item since `cursor` ordered by ascending last modified time. string The ID of the removed transaction. string The ID of the account of the removed transaction. string Cursor used for fetching any future updates after the latest update provided in this response. The cursor obtained after all pages have been pulled (indicated by `has_more` being `false`) will be valid for at least 1 year. This cursor should be persisted for later calls. If transactions are not yet available, this will be an empty string. boolean Represents if more than requested count of transaction updates exist. If true, the additional updates can be fetched by making an additional request with `cursor` set to `next_cursor`. If `has_more` is true, it’s important to pull all available pages, to make it less likely for underlying data changes to conflict with pagination. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "account": { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": 110.94, "current": 110.94, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" }, "added": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "account_owner": null, "amount": 72.1, "iso_currency_code": "USD", "unofficial_currency_code": null, "check_number": null, "counterparties": [ { "name": "Walmart", "type": "merchant", "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "website": "walmart.com", "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM", "confidence_level": "VERY_HIGH" } ], "date": "2023-09-24", "datetime": "2023-09-24T11:01:01Z", "authorized_date": "2023-09-22", "authorized_datetime": "2023-09-22T10:34:50Z", "location": { "address": "13425 Community Rd", "city": "Poway", "region": "CA", "postal_code": "92064", "country": "US", "lat": 32.959068, "lon": -117.037666, "store_number": "1700" }, "name": "PURCHASE WM SUPERCENTER #1700", "merchant_name": "Walmart", "merchant_entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM", "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "website": "walmart.com", "payment_meta": { "by_order_of": null, "payee": null, "payer": null, "payment_method": null, "payment_processor": null, "ppd_id": null, "reason": null, "reference_number": null }, "payment_channel": "in store", "pending": false, "pending_transaction_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc", "personal_finance_category": { "primary": "GENERAL_MERCHANDISE", "detailed": "GENERAL_MERCHANDISE_SUPERSTORES", "confidence_level": "VERY_HIGH" }, "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png", "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje", "transaction_code": null, "transaction_type": "place" } ], "modified": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "account_owner": null, "amount": 28.34, "iso_currency_code": "USD", "unofficial_currency_code": null, "check_number": null, "counterparties": [ { "name": "DoorDash", "type": "marketplace", "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png", "website": "doordash.com", "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm", "confidence_level": "HIGH" }, { "name": "Burger King", "type": "merchant", "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png", "website": "burgerking.com", "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1", "confidence_level": "VERY_HIGH" } ], "date": "2023-09-28", "datetime": "2023-09-28T15:10:09Z", "authorized_date": "2023-09-27", "authorized_datetime": "2023-09-27T08:01:58Z", "location": { "address": null, "city": null, "region": null, "postal_code": null, "country": null, "lat": null, "lon": null, "store_number": null }, "name": "Dd Doordash Burgerkin", "merchant_name": "Burger King", "merchant_entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1", "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png", "website": "burgerking.com", "payment_meta": { "by_order_of": null, "payee": null, "payer": null, "payment_method": null, "payment_processor": null, "ppd_id": null, "reason": null, "reference_number": null }, "payment_channel": "online", "pending": true, "pending_transaction_id": null, "personal_finance_category": { "primary": "FOOD_AND_DRINK", "detailed": "FOOD_AND_DRINK_FAST_FOOD", "confidence_level": "VERY_HIGH" }, "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png", "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0", "transaction_code": null, "transaction_type": "digital" } ], "removed": [ { "transaction_id": "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l", "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp" } ], "next_cursor": "tVUUL15lYQN5rBnfDIc1I8xudpGdIlw9nsgeXWvhOfkECvUeR663i3Dt1uf/94S8ASkitgLcIiOSqNwzzp+bh89kirazha5vuZHBb2ZA5NtCDkkV", "has_more": false, "request_id": "45QSn", "transactions_update_status": "HISTORICAL_UPDATE_COMPLETE" } ``` \=\*=\*=\*= #### /processor/transactions/get  #### Get transaction data  The [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) endpoint allows developers to receive user-authorized transaction data for credit, depository, and some loan-type accounts (only those with account subtype `student`; coverage may be limited). Transaction data is standardized across financial institutions, and in many cases transactions are linked to a clean name, entity type, location, and category. Similarly, account data is standardized and returned with a clean name, number, balance, and other meta information where available. Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift. Transactions are not immutable and can also be removed altogether by the institution; a removed transaction will no longer appear in [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) . For more details, see [Pending and posted transactions](https://plaid.com/docs/transactions/transactions-data/index.html.md#pending-and-posted-transactions) . Due to the potentially large number of transactions associated with a processor token, results are paginated. Manipulate the `count` and `offset` parameters in conjunction with the `total_transactions` response body field to fetch all available transactions. Data returned by [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) will be the data available for the processor token as of the most recent successful check for new transactions. Plaid typically checks for new data multiple times a day, but these checks may occur less frequently, such as once a day, depending on the institution. To force Plaid to check for new transactions, you can use the [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) endpoint. Note that data may not be immediately available to [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) . Plaid will begin to prepare transactions data upon Item link, if Link was initialized with `transactions`, or upon the first call to [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) , if it wasn't. If no transaction history is ready when [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) is called, it will return a `PRODUCT_NOT_READY` error. To receive Transactions webhooks for a processor token, set its webhook URL via the [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) endpoint. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. object An optional object to be used with the request. If specified, `options` must not be `null`. integer The number of transactions to fetch. Default: `100` Minimum: `1` Maximum: `500` Exclusive min: `false` integer The number of transactions to skip. The default value is 0. Default: `0` Minimum: `0` boolean Include the raw unparsed transaction description from the financial institution. Default: `false` required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: `date` required, string The latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: `date` ```node const request: ProcessorTransactionsGetRequest = { processor_token: processorToken, start_date: '2018-01-01', end_date: '2020-02-01' }; try { const response = await client.processorTransactionsGet(request); let transactions = response.data.transactions; const total_transactions = response.data.total_transactions; // Manipulate the offset parameter to paginate // transactions and retrieve all available data while (transactions.length < total_transactions) { const paginatedRequest: ProcessorTransactionsGetRequest = { processor_token: processorToken, start_date: '2018-01-01', end_date: '2020-02-01', options: { offset: transactions.length, }, }; const paginatedResponse = await client.processorTransactionsGet(paginatedRequest); transactions = transactions.concat( paginatedResponse.data.transactions, ); } } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/processor/transactions/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": String, "start_date": "2018-01-01", "end_date": "2018-02-01", "options": { "count": 250, "offset": 100 } }' ``` ```ruby # Pull transactions for a date range request = Plaid::ProcessorTransactionsGetRequest.new( { processor_token: processor_token, start_date: '2018-01-01', end_date: '2018-02-01' } ) response = client.processor_transactions_get(request) transactions = response.transactions # Manipulate the offset parameter to paginate # transactions and retrieve all available data while transactions.length < response.total_transactions request = Plaid::ProcessorTransactionsGetRequest.new( { processor_token: processor_token, start_date: '2018-01-01', end_date: '2018-02-01', options: { offset: transactions.length } } ) response = client.processor_transactions_get(request) transactions += response.transactions end ``` ```java SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd"); startDate = simpleDateFormat.parse("2018-01-01"); endDate = simpleDateFormat.parse("2018-02-01"); // Pull transactions for a date range ProcessorTransactionsGetRequest request = new ProcessorTransactionsGetRequest() .processorToken(processorToken) .startDate(startDate) .endDate(endDate); Response response = plaidClient.processorTransactionsGet(request).execute(); List transactions = new ArrayList (); transactions.addAll(response.body().getTransactions()); // Manipulate the offset parameter to paginate // transactions and retrieve all available data while (transactions.size() < response.body().getTotalTransactions()) { TransactionsGetRequestOptions options = new TransactionsGetRequestOptions() .offset(transactions.size()); ProcessorTransactionsGetRequest request = new ProcessorTransactionsGetRequest() .processorToken(processorToken) .startDate(startDate) .endDate(endDate) .options(options); Response response = plaidClient.processorTransactionsGet(request).execute(); transactions.addAll(response.body().getTransactions()); } ``` ```python request = ProcessorTransactionsGetRequest( processor_token=processor_token, start_date=datetime.date(2020, 1, 1), end_date=datetime.date(2021, 2, 1), options=TransactionsGetRequestOptions() ) response = client.processor_transactions_get(request) transactions = response['transactions'] # Manipulate the count and offset parameters to paginate # transactions and retrieve all available data while len(transactions) < response['total_transactions']: request = ProcessorTransactionsGetRequest( processor_token=processor_token, start_date=datetime.date(2018, 1, 1), end_date=datetime.date(2018, 2, 1), options=TransactionsGetRequestOptions( offset=len(transactions) ) ) response = client.processor_transactions_get(request) transactions.extend(response['transactions']) ``` ```go const iso8601TimeFormat = "2006-01-02" startDate := time.Now().Add(-365 * 24 * time.Hour).Format(iso8601TimeFormat) endDate := time.Now().Format(iso8601TimeFormat) request := plaid.NewProcessorTransactionsGetRequest( processorToken, startDate, endDate, ) options := plaid.TransactionsGetRequestOptions{ Count: plaid.PtrInt32(100), Offset: plaid.PtrInt32(0), } request.SetOptions(options) transactionsResp, _, err := client.PlaidApi.ProcessorTransactionsGet(ctx).ProcessorTransactionsGetRequest(*request).Execute() ``` #### Response fields  object A single account at a financial institution. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] An array containing transactions from the account. Transactions are returned in reverse chronological order, with the most recent at the beginning of the array. The maximum number of transactions returned is determined by the `count` parameter. string The ID of the account in which this transaction occurred. number The settled value of the transaction, denominated in the transactions's currency, as stated in `iso_currency_code` or `unofficial_currency_code`. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: `double` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The check number of the transaction. This field is only populated for check transactions. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). To receive information about the date that a posted transaction was initiated, see the `authorized_date` field. Format: `date` object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. deprecated, string The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use `merchant_name` instead for the merchant name. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, this field will always appear. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The merchant name, as enriched by Plaid from the `name` field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be `null`. nullable, string The string returned by the financial institution to describe the transaction. For transactions returned by `/transactions/sync` or `/transactions/get`, this field will only be included if the client has set `options.include_original_description` to `true`. object Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be `null`. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, the `payment_meta` key will always appear, but no data elements are guaranteed. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The transaction reference number supplied by the financial institution. nullable, string The ACH PPD ID for the payer. nullable, string For transfers, the party that is receiving the transaction. nullable, string The party initiating a wire transfer. Will be `null` if the transaction is not a wire transfer. nullable, string For transfers, the party that is paying the transaction. nullable, string The type of transfer, e.g. 'ACH' nullable, string The name of the payment processor nullable, string The payer-supplied description of the transfer. boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions. nullable, string The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions. nullable, string This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. deprecated, string Please use the `payment_channel` field, `transaction_type` will be deprecated in the future. `digital:` transactions that took place online. `place:` transactions that were made at a physical location. `special:` transactions that relate to banks, e.g. fees or deposits. `unresolved:` transactions that do not fit into the other three types. Possible values: `digital`, `place`, `special`, `unresolved` nullable, string The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file. nullable, string The website associated with this transaction, if available. nullable, string The date that the transaction was authorized. For posted transactions, the `date` field will indicate the posted date, but `authorized_date` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_date`, when available, is generally preferable to use over the `date` field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). Format: `date` nullable, string Date and time when a transaction was authorized in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For posted transactions, the `datetime` field will indicate the posted date, but `authorized_datetime` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_datetime`, when available, is generally preferable to use over the `datetime` field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` nullable, string Date and time when a transaction was posted in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For the date that the transaction was initiated, rather than posted, see the `authorized_datetime` field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` string The channel used to make a payment. `online:` transactions that took place online. `in store:` transactions that were made at a physical location. `other:` transactions that relate to banks, e.g. fees or deposits. This field replaces the `transaction_type` field. Possible values: `online`, `in store`, `other` nullable, object Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the [taxonomy CSV file](https://plaid.com/documents/pfc-taxonomy-all.csv) for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the [migration guide](https://plaid.com/docs/transactions/pfc-migration/index.html.md) . string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string A description of how confident we are that the provided categories accurately describe the transaction intent. `VERY_HIGH`: We are more than 98% confident that this category reflects the intent of the transaction. `HIGH`: We are more than 90% confident that this category reflects the intent of the transaction. `MEDIUM`: We are moderately confident that this category reflects the intent of the transaction. `LOW`: This category may reflect the intent, but there may be other categories that are more accurate. `UNKNOWN`: We don’t know the confidence level for this category. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` nullable, string An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to `null`. `adjustment:` Bank adjustment `atm:` Cash deposit or withdrawal via an automated teller machine `bank charge:` Charge or fee levied by the institution `bill payment`: Payment of a bill `cash:` Cash deposit or withdrawal `cashback:` Cash withdrawal while making a debit card purchase `cheque:` Document ordering the payment of money to another person or organization `direct debit:` Automatic withdrawal of funds initiated by a third party at a regular interval `interest:` Interest earned or incurred `purchase:` Purchase made with a debit or credit card `standing order:` Payment instructed by the account holder to a third party at a regular interval `transfer:` Transfer of money between accounts Possible values: `adjustment`, `atm`, `bank charge`, `bill payment`, `cash`, `cashback`, `cheque`, `direct debit`, `interest`, `purchase`, `standing order`, `transfer`, `null` string The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file. \[object\] The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description. string The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description. nullable, string A unique, stable, Plaid-generated ID that maps to the counterparty. string The counterparty type. `merchant`: a provider of goods or services for purchase `financial_institution`: a financial entity (bank, credit union, BNPL, fintech) `payment_app`: a transfer or P2P app (e.g. Zelle) `marketplace`: a marketplace (e.g DoorDash, Google Play Store) `payment_terminal`: a point-of-sale payment terminal (e.g Square, Toast) `income_source`: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: `merchant`, `financial_institution`, `payment_app`, `marketplace`, `payment_terminal`, `income_source` nullable, string The website associated with the counterparty. nullable, string The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file. nullable, string A description of how confident we are that the provided counterparty is involved in the transaction. `VERY_HIGH`: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. `HIGH`: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. `MEDIUM`: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. `LOW`: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. `UNKNOWN`: We don’t know the confidence level for this counterparty. nullable, object Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe. nullable, object Identifying information for a UK bank account via BACS. nullable, string The BACS account number for the account. nullable, string The BACS sort code for the account. nullable, object Account numbers using the International Bank Account Number and BIC/SWIFT code format. nullable, string International Bank Account Number (IBAN). Min length: `15` Max length: `34` nullable, string Bank identifier code (BIC) for this counterparty. Min length: `8` Max length: `11` nullable, string A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store. integer The total number of transactions available within the date range specified. If `total_transactions` is larger than the size of the `transactions` array, more transactions are available and can be fetched via manipulating the `offset` parameter. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "account": { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": 110.94, "current": 110.94, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" }, "transactions": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "account_owner": null, "amount": 28.34, "iso_currency_code": "USD", "unofficial_currency_code": null, "check_number": null, "counterparties": [ { "name": "DoorDash", "type": "marketplace", "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png", "website": "doordash.com", "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm", "confidence_level": "HIGH" }, { "name": "Burger King", "type": "merchant", "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png", "website": "burgerking.com", "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1", "confidence_level": "VERY_HIGH" } ], "date": "2023-09-28", "datetime": "2023-09-28T15:10:09Z", "authorized_date": "2023-09-27", "authorized_datetime": "2023-09-27T08:01:58Z", "location": { "address": null, "city": null, "region": null, "postal_code": null, "country": null, "lat": null, "lon": null, "store_number": null }, "name": "Dd Doordash Burgerkin", "merchant_name": "Burger King", "merchant_entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1", "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png", "website": "burgerking.com", "payment_meta": { "by_order_of": null, "payee": null, "payer": null, "payment_method": null, "payment_processor": null, "ppd_id": null, "reason": null, "reference_number": null }, "payment_channel": "online", "pending": true, "pending_transaction_id": null, "personal_finance_category": { "primary": "FOOD_AND_DRINK", "detailed": "FOOD_AND_DRINK_FAST_FOOD", "confidence_level": "VERY_HIGH" }, "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png", "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0", "transaction_code": null, "transaction_type": "digital" }, { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "account_owner": null, "amount": 72.1, "iso_currency_code": "USD", "unofficial_currency_code": null, "check_number": null, "counterparties": [ { "name": "Walmart", "type": "merchant", "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "website": "walmart.com", "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM", "confidence_level": "VERY_HIGH" } ], "date": "2023-09-24", "datetime": "2023-09-24T11:01:01Z", "authorized_date": "2023-09-22", "authorized_datetime": "2023-09-22T10:34:50Z", "location": { "address": "13425 Community Rd", "city": "Poway", "region": "CA", "postal_code": "92064", "country": "US", "lat": 32.959068, "lon": -117.037666, "store_number": "1700" }, "name": "PURCHASE WM SUPERCENTER #1700", "merchant_name": "Walmart", "merchant_entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM", "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "website": "walmart.com", "payment_meta": { "by_order_of": null, "payee": null, "payer": null, "payment_method": null, "payment_processor": null, "ppd_id": null, "reason": null, "reference_number": null }, "payment_channel": "in store", "pending": false, "pending_transaction_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc", "personal_finance_category": { "primary": "GENERAL_MERCHANDISE", "detailed": "GENERAL_MERCHANDISE_SUPERSTORES", "confidence_level": "VERY_HIGH" }, "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png", "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje", "transaction_code": null, "transaction_type": "place" } ], "total_transactions": 1, "request_id": "Wvhy9PZHQLV8njG" } ``` \=\*=\*=\*= #### /processor/transactions/recurring/get  #### Fetch recurring transaction streams  The [/processor/transactions/recurring/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrecurringget) endpoint allows developers to receive a summary of the recurring outflow and inflow streams (expenses and deposits) from a user’s checking, savings or credit card accounts. Additionally, Plaid provides key insights about each recurring stream including the category, merchant, last amount, and more. Developers can use these insights to build tools and experiences that help their users better manage cash flow, monitor subscriptions, reduce spend, and stay on track with bill payments. This endpoint is offered as an add-on to Transactions. To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/team/products) or contact your Plaid account manager. This endpoint can only be called on a processor token that has already been initialized with Transactions (either during Link, by specifying it in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; or after Link, by calling [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) or [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) ). Once all historical transactions have been fetched, call [/processor/transactions/recurring/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrecurringget) to receive the Recurring Transactions streams and subscribe to the [RECURRING\_TRANSACTIONS\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#recurring_transactions_update) webhook. To know when historical transactions have been fetched, if you are using [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) listen for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#SyncUpdatesAvailableWebhook-historical-update-complete) webhook and check that the `historical_update_complete` field in the payload is `true`. If using [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) , listen for the [HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#historical_update) webhook. After the initial call, you can call [/processor/transactions/recurring/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrecurringget) endpoint at any point in the future to retrieve the latest summary of recurring streams. Listen to the [RECURRING\_TRANSACTIONS\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#recurring_transactions_update) webhook to be notified when new updates are available. To receive Transactions webhooks for a processor token, set its webhook URL via the [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) endpoint. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. object An optional object to be used with the request. If specified, `options` must not be `null`. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` ```bash curl -X POST https://sandbox.plaid.com/processor/transactions/recurring/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token":"processor-sandbox-12345678-1234-abcd-9c8f-fd5406010eee" }' ``` ```node const request: ProcessorTransactionsGetRequest = { processor_token: processorToken }; try { const response = await client.processorTransactionsRecurringGet(request); let inflowStreams = response.data.inflowStreams; let outflowStreams = response.data.outflowStreams; } catch (error) { // handle error } ``` ```python request = ProcessorTransactionsRecurringGetRequest( processor_token=processor_token ) response = client.processor_transactions_recurring_get(request) inflow_streams = response.inflow_streams outflow_streams = response.outflow_streams ``` ```ruby request = Plaid::ProcessorTransactionsRecurringGetRequest.new( { processor_token: processor_token } ) response = client.processor_transactions_recurring_get(request) inflowStreams = response.inflowStreams outflowStreams = response.outflowStreams ``` ```java ProcessorTransactionsRecurringGetRequest request = new ProcessorTransactionsRecurringGetRequest() .processorToken(processorToken); Response response = plaidClient.processorTransactionsRecurringGet(request).execute(); List inflowStreams = new ArrayList (); inflowStreams.addAll(response.body().getInflowStreams()); List outflowStreams = new ArrayList (); outflowStreams.addAll(response.body().getOutflowStreams()); ``` ```go request := plaid.NewProcessorTransactionsRecurringGetRequest( processorToken ) response, _, err := client.PlaidApi.ProcessorTransactionsRecurringGet(ctx).ProcessorTransactionsRecurringGetRequest(*request).Execute() ``` #### Response fields  \[object\] An array of depository transaction streams. string The ID of the account to which the stream belongs string A unique id for the stream string A description of the transaction stream. nullable, string The merchant associated with the transaction stream. string The posted date of the earliest transaction in the stream. Format: `date` string The posted date of the latest transaction in the stream. Format: `date` nullable, string The predicted date of the next payment. This will only be set if the next payment date can be predicted. Format: `date` string Describes the frequency of the transaction stream. `WEEKLY`: Assigned to a transaction stream that occurs approximately every week. `BIWEEKLY`: Assigned to a transaction stream that occurs approximately every 2 weeks. `SEMI_MONTHLY`: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams. `MONTHLY`: Assigned to a transaction stream that occurs approximately every month. `ANNUALLY`: Assigned to a transaction stream that occurs approximately every year. `UNKNOWN`: Assigned to a transaction stream that does not fit any of the pre-defined frequencies. Possible values: `UNKNOWN`, `WEEKLY`, `BIWEEKLY`, `SEMI_MONTHLY`, `MONTHLY`, `ANNUALLY` \[string\] An array of Plaid transaction IDs belonging to the stream, sorted by posted date. object Object with data pertaining to an amount on the transaction stream. number Represents the numerical value of an amount. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. object Object with data pertaining to an amount on the transaction stream. number Represents the numerical value of an amount. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. boolean Indicates whether the transaction stream is still live. string The current status of the transaction stream. `MATURE`: A `MATURE` recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it `MATURE` after 2 instances). `EARLY_DETECTION`: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be `EARLY_DETECTION`. `TOMBSTONED`: A stream that was previously in the `EARLY_DETECTION` status will move to the `TOMBSTONED` status when no further transactions were found at the next expected date. `UNKNOWN`: A stream is assigned an `UNKNOWN` status when none of the other statuses are applicable. Possible values: `UNKNOWN`, `MATURE`, `EARLY_DETECTION`, `TOMBSTONED` nullable, object Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the [taxonomy CSV file](https://plaid.com/documents/pfc-taxonomy-all.csv) for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the [migration guide](https://plaid.com/docs/transactions/pfc-migration/index.html.md) . string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string A description of how confident we are that the provided categories accurately describe the transaction intent. `VERY_HIGH`: We are more than 98% confident that this category reflects the intent of the transaction. `HIGH`: We are more than 90% confident that this category reflects the intent of the transaction. `MEDIUM`: We are moderately confident that this category reflects the intent of the transaction. `LOW`: This category may reflect the intent, but there may be other categories that are more accurate. `UNKNOWN`: We don’t know the confidence level for this category. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` deprecated, boolean As the ability to modify transactions streams has been discontinued, this field will always be `false`. \[object\] An array of expense transaction streams. string The ID of the account to which the stream belongs string A unique id for the stream string A description of the transaction stream. nullable, string The merchant associated with the transaction stream. string The posted date of the earliest transaction in the stream. Format: `date` string The posted date of the latest transaction in the stream. Format: `date` nullable, string The predicted date of the next payment. This will only be set if the next payment date can be predicted. Format: `date` string Describes the frequency of the transaction stream. `WEEKLY`: Assigned to a transaction stream that occurs approximately every week. `BIWEEKLY`: Assigned to a transaction stream that occurs approximately every 2 weeks. `SEMI_MONTHLY`: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams. `MONTHLY`: Assigned to a transaction stream that occurs approximately every month. `ANNUALLY`: Assigned to a transaction stream that occurs approximately every year. `UNKNOWN`: Assigned to a transaction stream that does not fit any of the pre-defined frequencies. Possible values: `UNKNOWN`, `WEEKLY`, `BIWEEKLY`, `SEMI_MONTHLY`, `MONTHLY`, `ANNUALLY` \[string\] An array of Plaid transaction IDs belonging to the stream, sorted by posted date. object Object with data pertaining to an amount on the transaction stream. number Represents the numerical value of an amount. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. object Object with data pertaining to an amount on the transaction stream. number Represents the numerical value of an amount. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. boolean Indicates whether the transaction stream is still live. string The current status of the transaction stream. `MATURE`: A `MATURE` recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it `MATURE` after 2 instances). `EARLY_DETECTION`: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be `EARLY_DETECTION`. `TOMBSTONED`: A stream that was previously in the `EARLY_DETECTION` status will move to the `TOMBSTONED` status when no further transactions were found at the next expected date. `UNKNOWN`: A stream is assigned an `UNKNOWN` status when none of the other statuses are applicable. Possible values: `UNKNOWN`, `MATURE`, `EARLY_DETECTION`, `TOMBSTONED` nullable, object Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the [taxonomy CSV file](https://plaid.com/documents/pfc-taxonomy-all.csv) for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the [migration guide](https://plaid.com/docs/transactions/pfc-migration/index.html.md) . string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string A description of how confident we are that the provided categories accurately describe the transaction intent. `VERY_HIGH`: We are more than 98% confident that this category reflects the intent of the transaction. `HIGH`: We are more than 90% confident that this category reflects the intent of the transaction. `MEDIUM`: We are moderately confident that this category reflects the intent of the transaction. `LOW`: This category may reflect the intent, but there may be other categories that are more accurate. `UNKNOWN`: We don’t know the confidence level for this category. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` deprecated, boolean As the ability to modify transactions streams has been discontinued, this field will always be `false`. string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time transaction streams for the given account were updated on Format: `date-time` string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "updated_datetime": "2022-05-01T00:00:00Z", "inflow_streams": [ { "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje", "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc", "category": null, "category_id": null, "description": "Platypus Payroll", "merchant_name": null, "personal_finance_category": { "primary": "INCOME", "detailed": "INCOME_WAGES", "confidence_level": "UNKNOWN" }, "first_date": "2022-02-28", "last_date": "2022-04-30", "predicted_next_date": "2022-05-15", "frequency": "SEMI_MONTHLY", "transaction_ids": [ "nkeaNrDGrhdo6c4qZWDA8ekuIPuJ4Avg5nKfw", "EfC5ekksdy30KuNzad2tQupW8WIPwvjXGbGHL", "ozfvj3FFgp6frbXKJGitsDzck5eWQH7zOJBYd", "QvdDE8AqVWo3bkBZ7WvCd7LskxVix8Q74iMoK", "uQozFPfMzibBouS9h9tz4CsyvFll17jKLdPAF" ], "average_amount": { "amount": -800, "iso_currency_code": "USD", "unofficial_currency_code": null }, "last_amount": { "amount": -1000, "iso_currency_code": "USD", "unofficial_currency_code": null }, "is_active": true, "status": "MATURE", "is_user_modified": false } ], "outflow_streams": [ { "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff", "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nd", "category": null, "category_id": null, "description": "ConEd Bill Payment", "merchant_name": "ConEd", "personal_finance_category": { "primary": "RENT_AND_UTILITIES", "detailed": "RENT_AND_UTILITIES_GAS_AND_ELECTRICITY", "confidence_level": "UNKNOWN" }, "first_date": "2022-02-04", "last_date": "2022-05-02", "predicted_next_date": "2022-06-02", "frequency": "MONTHLY", "transaction_ids": [ "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0", "HPDnUVgI5Pa0YQSl0rxwYRwVXeLyJXTWDAvpR", "jEPoSfF8xzMClE9Ohj1he91QnvYoSdwg7IT8L", "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l" ], "average_amount": { "amount": 85, "iso_currency_code": "USD", "unofficial_currency_code": null }, "last_amount": { "amount": 100, "iso_currency_code": "USD", "unofficial_currency_code": null }, "is_active": true, "status": "MATURE", "is_user_modified": false }, { "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff", "stream_id": "SrBNJZDuUMweodmPmSOeOImwsWt53ZXfJQAfC", "category": null, "category_id": null, "description": "Costco Annual Membership", "merchant_name": "Costco", "personal_finance_category": { "primary": "GENERAL_MERCHANDISE", "detailed": "GENERAL_MERCHANDISE_SUPERSTORES", "confidence_level": "UNKNOWN" }, "first_date": "2022-01-23", "last_date": "2023-01-22", "predicted_next_date": "2024-01-22", "frequency": "ANNUALLY", "transaction_ids": [ "yqEBJ72cS4jFwcpxJcDuQr94oAQ1R1lMC33D4", "Kz5Hm3cZCgpn4tMEKUGAGD6kAcxMBsEZDSwJJ" ], "average_amount": { "amount": 120, "iso_currency_code": "USD", "unofficial_currency_code": null }, "last_amount": { "amount": 120, "iso_currency_code": "USD", "unofficial_currency_code": null }, "is_active": true, "status": "MATURE", "is_user_modified": false } ], "request_id": "tbFyCEqkU775ZGG" } ``` \=\*=\*=\*= #### /processor/transactions/refresh  #### Refresh transaction data  [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) is an optional endpoint for users of the Transactions product. It initiates an on-demand extraction to fetch the newest transactions for a processor token. This on-demand extraction takes place in addition to the periodic extractions that automatically occur one or more times per day for any Transactions-enabled processor token. If changes to transactions are discovered after calling [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) , Plaid will fire a webhook: for [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) users, [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) will be fired if there are any transactions updated, added, or removed. For users of both [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) and [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) , [TRANSACTIONS\_REMOVED](https://plaid.com/docs/api/products/transactions/index.html.md#transactions_removed) will be fired if any removed transactions are detected, and [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#default_update) will be fired if any new transactions are detected. New transactions can be fetched by calling [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) or [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) . Note that the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint is not supported for Capital One (`ins_128026`) non-depository accounts and will result in a `PRODUCTS_NOT_SUPPORTED` error if called on an Item that contains only non-depository accounts from that institution. As this endpoint triggers a synchronous request for fresh data, latency may be higher than for other Plaid endpoints (typically less than 10 seconds, but occasionally up to 30 seconds or more); if you encounter errors, you may find it necessary to adjust your timeout period when making requests. [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) is offered as an add-on to Transactions and has a separate [fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/team/products) or contact your Plaid account manager. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```bash curl -X POST https://sandbox.plaid.com/processor/transactions/refresh \ -H 'content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": String, }' ``` ```node const request: ProcessorTransactionsRefreshRequest = { processor_token: processorToken, }; try { await plaidClient.processorTransactionsRefresh(request); } catch (error) { // handle error } ``` ```ruby request = Plaid::ProcessorTransactionsRefreshRequest.new({ processor_token: processor_token }) response = client.processor_transactions_refresh(request) ``` ```java ProcessorTransactionsRefreshRequest request = new ProcessorTransactionsRefreshRequest() .processorToken(processorToken); Response response = client() .processorTransactionsRefresh(request) .execute(); ``` ```python request = ProcessorTransactionsRefreshRequest(processor_token=processor_token) response = client.processor_transactions_refresh(request) ``` ```go request := plaid.NewProcessorTransactionsRefreshRequest(processorToken) response, _, err := client.PlaidApi.ProcessorTransactionsRefresh(ctx).ProcessorTransactionsRefreshRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "1vwmF5TBQwiqfwP" } ``` Processor webhooks  ------------------- \=\*=\*=\*= #### WEBHOOK\_UPDATE\_ACKNOWLEDGED  This webhook is only sent to [Plaid processor partners](https://plaid.com/docs/auth/partnerships/index.html.md) . Fired when a processor updates the webhook URL for a processor token via [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) . #### Properties  string `PROCESSOR_TOKEN` string `WEBHOOK_UPDATE_ACKNOWLEDGED` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The ID of the account. string The new webhook URL. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "PROCESSOR_TOKEN", "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED", "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "new_webhook_url": "https://www.example.com", "error": null, "environment": "production" } ``` --- # API - Processor tokens | Plaid Docs Processor token endpoints  ========================== #### API reference for endpoints for use with Plaid partners  Processor token endpoints are used to create tokens that are then sent to a Plaid partner for use in a Plaid integration. For a full list of integrations, see the [Plaid Dashboard](https://dashboard.plaid.com/developers/integrations) . For specific information on Auth integrations, see [Auth payment partners](https://plaid.com/docs/auth/partnerships/index.html.md) . Are you a Plaid processor partner looking for API docs? The documentation on API endpoints for use by partners has moved to [Processor partner endpoints](https://plaid.com/docs/api/processor-partners/index.html.md) . | In this section | | | --- | --- | | [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) | Create a processor token | | [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) | Create a bank account token for use with Stripe | | [/processor/token/permissions/set](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsset) | Set product permissions for a processor token | | [/processor/token/permissions/get](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsget) | Get product permissions for a processor token | | See also | | | --- | --- | | [/sandbox/processor\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxprocessor_tokencreate) | Create a test Item and processor token (Sandbox only) | \=\*=\*=\*= #### /processor/token/create  #### Create processor token  Used to create a token suitable for sending to one of Plaid's partners to enable integrations. Note that Stripe partnerships use bank account tokens instead; see [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) for creating tokens for use with Stripe integrations. If using multiple processors, multiple different processor tokens can be created for a single access token. Once created, a processor token for a given Item can be modified by calling [/processor/token/permissions/set](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsset) . To revoke the processor's access, the entire Item must be deleted by calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. required, string The `account_id` value obtained from the `onSuccess` callback in Link required, string The processor you are integrating with. Possible values: `dwolla`, `galileo`, `modern_treasury`, `ocrolus`, `vesta`, `drivewealth`, `vopay`, `achq`, `check`, `checkbook`, `circle`, `sila_money`, `rize`, `svb_api`, `unit`, `wyre`, `lithic`, `alpaca`, `astra`, `moov`, `treasury_prime`, `marqeta`, `checkout`, `solid`, `highnote`, `gemini`, `apex_clearing`, `gusto`, `adyen`, `atomic`, `i2c`, `wepay`, `riskified`, `utb`, `adp_roll`, `fortress_trust`, `bond`, `bakkt`, `teal`, `zero_hash`, `taba_pay`, `knot`, `sardine`, `alloy`, `finix`, `nuvei`, `layer`, `boom`, `paynote`, `stake`, `wedbush`, `esusu`, `ansa`, `scribeup`, `straddle`, `loanpro`, `bloom_credit`, `sfox`, `brale`, `parafin`, `cardless`, `open_ledger`, `valon`, `gainbridge`, `cardlytics`, `pinwheel`, `thread_bank`, `array`, `fiant`, `oatfi`, `curinos` ```bash # Exchange the public token from Plaid Link for an access token. curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "${PUBLIC_TOKEN}" }' \ -X POST \ https://sandbox.plaid.com/item/public_token/exchange # Create a processor token for a specific account id. curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}", "account_id": "${ACCOUNT_ID}", "processor": "dwolla" }' \ -X POST \ https://sandbox.plaid.com/processor/token/create ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; import com.plaid.client.model.ProcessorTokenCreateRequest; import com.plaid.client.model.ProcessorTokenCreateResponse; // Change sandbox to development to test with live users; // Change to production when you're ready to go live! HashMap apiKeys = new HashMap(); apiKeys.put("clientId", plaidClientId); apiKeys.put("secret", plaidSecret); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange the public token from Plaid Link for an access token. ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response exchangeResponse = client() .itemPublicTokenExchange(request) .execute(); // Create a processor token for a specific account id. if (exchangeResponse.isSuccessful()) { String accessToken = exchangeResponse.body().getAccessToken(); ProcessorTokenCreateRequest request = new ProcessorTokenCreateRequest() .accessToken(accessToken) .processor("dwolla") .accountId(accountID); Response dwollaResponse = client() .processorTokenCreate(request) .execute(); if (dwollaResponse.isSuccessful()) { String dwollaProcessorToken = dwollaResponse.body().getProcessorToken(); } } ``` ```ruby require 'plaid' # Change sandbox to development to test with live users; # Change to production when you're ready to go live! configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] =ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] configuration.api_key['Plaid-Version'] = '2020-09-14' api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) # Exchange the public token from Plaid Link for an access token. item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: public_token } ) exchange_token_response = client.item_public_token_exchange(item_public_token_exchange_request) access_token = exchange_token_response.access_token # Create a processor token for a specific account id. processor_token_create_request = Plaid::ProcessorTokenCreateRequest.new( { access_token: access_token, account_id: account_id, processor: "dwolla" } ) create_response = client.processor_token_create(processor_token_create_request) processor_token = create_response.processor_token ``` ```python import plaid from plaid.api import plaid_api from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest from plaid.model.processor_token_create_request import ProcessorTokenCreateRequest # Change sandbox to development to test with live users; # Change to production when you're ready to go live! configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, 'plaidVersion': '2020-09-14' } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Exchange the public token from Plaid Link for an access token. exchange_request = ItemPublicTokenExchangeRequest(public_token=public_token) exchange_token_response = client.item_public_token_exchange(exchange_request) access_token = exchange_token_response['access_token'] # Create a processor token for a specific account id. create_request = ProcessorTokenCreateRequest( access_token=access_token, account_id=account_id, processor='dwolla' ) create_response = client.processor_token_create(create_request) processor_token = create_response['processor_token'] ``` ```node const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest, } = require('plaid'); // Change sandbox to development to test with live users; // Change to production when you're ready to go live! const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, 'Plaid-Version': '2020-09-14', }, }, }); const plaidClient = new PlaidApi(configuration); try { // Exchange the public_token from Plaid Link for an access token. const tokenResponse = await plaidClient.itemPublicTokenExchange({ public_token: PUBLIC_TOKEN, }); const accessToken = tokenResponse.data.access_token; // Create a processor token for a specific account id. const request: ProcessorTokenCreateRequest = { access_token: accessToken, account_id: accountID, processor: 'dwolla', }; const processorTokenResponse = await plaidClient.processorTokenCreate( request, ); const processorToken = processorTokenResponse.data.processor_token; } catch (error) { // handle error } ``` ```go import ( "context" "os" plaid "github.com/plaid/plaid-go/v40/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) ctx := context.Background() // If not testing in Sandbox, remove these four lines and instead use a publicToken obtained from Link sandboxInstitution := "ins_109508" testProducts := []string{"auth"} sandboxPublicTokenResp, _, err := client.PlaidApi.SandboxPublicTokenCreate(ctx).SandboxPublicTokenCreateRequest( *plaid.NewSandboxPublicTokenCreateRequest( sandboxInstitution, testProducts, ), ).Execute() publicToken := sandboxPublicTokenResp.GetPublicToken() // Exchange the publicToken for an accessToken exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest(publicToken), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() // Get Accounts accountsGetResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest( *plaid.NewAccountsGetRequest(accessToken), ).Execute() accountID := accountsGetResp.GetAccounts()[0].GetAccountId() // Create processor token processorTokenCreateResp, _, err := client.PlaidApi.ProcessorTokenCreate(ctx).ProcessorTokenCreateRequest( *plaid.NewProcessorTokenCreateRequest(accessToken, accountID, "dwolla"), ).Execute() ``` #### Response fields  string The `processor_token` that can then be used by the Plaid partner to make API requests string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "processor_token": "processor-sandbox-0asd1-a92nc", "request_id": "xrQNYZ7Zoh6R7gV" } ``` \=\*=\*=\*= #### /processor/token/permissions/set  #### Control a processor's access to products  Used to control a processor's access to products on the given processor token. By default, a processor will have access to all available products on the corresponding item. To restrict access to a particular set of products, call this endpoint with the desired products. To restore access to all available products, call this endpoint with an empty list. This endpoint can be called multiple times as your needs and your processor's needs change. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` required, \[string\] A list of products the processor token should have access to. An empty list will grant access to all products. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` ```bash curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": "${PROCESSOR_TOKEN}", "products": ["auth", "balance", "identity"], }' \ -X POST \ https://sandbox.plaid.com/processor/token/permissions/set ``` ```java ProcessorTokenPermissionsSetRequest request = new ProcessorTokenPermissionsSetRequest() .processorToken(processorToken) .products(products); // List Response response = client() .processorTokenPermissionsSet(request) .execute(); ``` ```ruby processor_token_permissions_set_request = Plaid::ProcessorTokenPermissionsSetRequest.new( { processor_token: processor_token, products: products } ) response = client.processor_token_permissions_set(processor_token_permissions_set_request) ``` ```python request = ProcessorTokenPermissionsSetRequest( processor_token=processor_token, products=products # [Products] ) response = client.processor_token_permissions_set(request) ``` ```node try { const request: ProcessorTokenPermissionsSetRequest = { processor_token: processorToken, products: ['auth', 'balance', 'identity'], }; const response = await plaidClient.processorTokenPermissionsSet(request); } catch (error) { // handle error } ``` ```go processorTokenPermissionsSetResp, _, err := client.PlaidApi.ProcessorTokenPermissionsSet(ctx).ProcessorTokenPermissionsSetRequest( *plaid.NewProcessorTokenPermissionsSetRequest(processorToken, products), ).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "xrQNYZ7Zoh6R7gV" } ``` \=\*=\*=\*= #### /processor/token/permissions/get  #### Get a processor token's product permissions  Used to get a processor token's product permissions. The `products` field will be an empty list if the processor can access all available products. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The processor token obtained from the Plaid integration partner. Processor tokens are in the format: `processor--` ```bash curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "processor_token": "${PROCESSOR_TOKEN}" }' \ -X POST \ https://sandbox.plaid.com/processor/token/permissions/get ``` ```java ProcessorTokenPermissionsGetRequest request = new ProcessorTokenPermissionsGetRequest() .processorToken(processorToken); Response response = client() .processorTokenPermissionsGet(request) .execute(); List products = response.body().getProducts(); ``` ```ruby processor_token_permissions_get_request = Plaid::ProcessorTokenPermissionsGetRequest.new( { processor_token: processor_token, } ) response = client.processor_token_permissions_get(processor_token_permissions_get_request) products = response.products ``` ```python request = ProcessorTokenPermissionsGetRequest( processor_token=processor_token, ) response = client.processor_token_permissions_get(request) products = response['products'] ``` ```node try { const request: ProcessorTokenPermissionsGetRequest = { processor_token: processorToken, }; const response = await plaidClient.processorTokenPermissionsGet(request); const products = response.data.products; } catch (error) { // handle error } ``` ```go processorTokenPermissionsGetResp, _, err := client.PlaidApi.ProcessorTokenPermissionsGet(ctx).ProcessorTokenPermissionsGetRequest( *plaid.NewProcessorTokenPermissionsGetRequest(processorToken), ).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. \[string\] A list of products the processor token should have access to. An empty list means that the processor has access to all available products, including future products. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` Response Object ```json { "request_id": "xrQNYZ7Zoh6R7gV", "products": [ "auth", "balance", "identity" ] } ``` \=\*=\*=\*= #### /processor/stripe/bank\_account\_token/create  #### Create Stripe bank account token  Used to create a token suitable for sending to Stripe to enable Plaid-Stripe integrations. For a detailed guide on integrating Stripe, see [Add Stripe to your app](https://plaid.com/docs/auth/partnerships/stripe/index.html.md) . Note that the Stripe bank account token is a one-time use token. To store bank account information for later use, you can use a Stripe customer object and create an associated bank account from the token, or you can use a Stripe Custom account and create an associated external bank account from the token. This bank account information should work indefinitely, unless the user's bank account information changes or they revoke Plaid's permissions to access their account. Stripe bank account information cannot be modified once the bank account token has been created. If you ever need to change the bank account details used by Stripe for a specific customer, have the user go through Link again and create a new bank account token from the new `access_token`. To revoke a bank account token, the entire underlying access token must be revoked using [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. required, string The `account_id` value obtained from the `onSuccess` callback in Link ```node // Change sandbox to development to test with live users and change // to production when you're ready to go live! const { Configuration, PlaidApi, PlaidEnvironments, ProcessorStripeBankAccountTokenCreateRequest, } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments[process.env.PLAID_ENV], baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, 'Plaid-Version': '2020-09-14', }, }, }); const plaidClient = new PlaidApi(configuration); try { // Exchange the public_token from Plaid Link for an access token. const tokenResponse = await plaidClient.itemPublicTokenExchange({ public_token: PUBLIC_TOKEN, }); const accessToken = tokenResponse.data.access_token; // Generate a bank account token const request: ProcessorStripeBankAccountTokenCreateRequest = { access_token: accessToken, account_id: accountID, }; const stripeTokenResponse = await plaidClient.processorStripeBankAccountTokenCreate( request, ); const bankAccountToken = stripeTokenResponse.data.stripe_bank_account_token; } catch (error) { // handle error } ``` ```bash # Exchange token curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "${PUBLIC_TOKEN}" }' # Create bank account token curl -X POST https://sandbox.plaid.com/processor/stripe/bank_account_token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}", "account_id": "${ACCOUNT_ID}" }' ``` ```ruby require 'plaid' # Change sandbox to development to test with live users and change # to production when you're ready to go live! configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] =ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] configuration.api_key['Plaid-Version'] = '2020-09-14' api_client = Plaid::ApiClient.new( configuration ) item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: public_token } ) exchange_token_response = client.item_public_token_exchange(item_public_token_exchange_request) access_token = exchange_token_response.access_token processor_token_create_request = Plaid::ProcessorStripeBankAccountTokenCreateRequest.new( { access_token: access_token, account_id: account_id } ) stripe_response = client.processor_stripe_bank_account_token_create(processor_token_create_request) bank_account_token = stripe_response.stripe_bank_account_token ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; import com.plaid.client.model.ProcessorStripeBankAccountTokenCreateRequest; import com.plaid.client.model.ProcessorStripeBankAccountTokenCreateResponse; // Change sandbox to development to test with live users; // Change to production when you're ready to go live! HashMap apiKeys = new HashMap(); apiKeys.put("clientId", plaidClientId); apiKeys.put("secret", plaidSecret); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange the public token from Plaid Link for an access token. ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response exchangeResponse = client() .itemPublicTokenExchange(request) .execute(); if (exchangeResponse.isSuccessful()) { String accessToken = exchangeResponse.body().getAccessToken(); ProcessorStripeBankAccountTokenCreateRequest request = new ProcessorStripeBankAccountTokenCreateRequest() .accessToken(accessToken) .accountId("FooBarAccountId"); Response stripeResponse = client() .processorStripeBankAccountTokenCreate(request) .execute(); if (stripeResponse.isSuccessful()) { String bankAccountToken = stripeResponse.body().getStripeBankAccountToken(); } } ``` ```python import plaid from plaid.api import plaid_api from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest from plaid.model.processor_stripe_token_create_request import ProcessorStripeBankAccountTokenCreateRequest # Change sandbox to development to test with live users and change # to production when you're ready to go live! configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, 'plaidVersion': '2020-09-14' } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) exchange_request = ItemPublicTokenExchangeRequest(public_token=public_token) exchange_token_response = client.item_public_token_exchange(exchange_request) access_token = exchange_token_response['access_token'] request = ProcessorStripeBankAccountTokenCreateRequest( access_token=access_token, account_id=account_id, ) stripe_response = client.processor_stripe_bank_account_token_create(request) bank_account_token = stripe_response['stripe_bank_account_token'] ``` ```go import ( "context" "os" plaid "github.com/plaid/plaid-go/v40/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) ctx := context.Background() // If not testing in Sandbox, remove these four lines and instead use a publicToken obtained from Link sandboxInstitution := "ins_109508" testProducts := []string{"auth"} sandboxPublicTokenResp, _, err := client.PlaidApi.SandboxPublicTokenCreate(ctx).SandboxPublicTokenCreateRequest( *plaid.NewSandboxPublicTokenCreateRequest( sandboxInstitution, testProducts, ), ).Execute() publicToken := sandboxPublicTokenResp.GetPublicToken() // Exchange the publicToken for an accessToken exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest(publicToken), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() // Get Accounts accountsGetResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest( *plaid.NewAccountsGetRequest(accessToken), ).Execute() accountID := accountsGetResp.GetAccounts()[0].GetAccountId() // Create Stripe token stripeTokenCreateResp, _, err := client.PlaidApi.ProcessorStripeBankAccountTokenCreate(ctx).ProcessorStripeBankAccountTokenCreateRequest( *plaid.NewProcessorStripeBankAccountTokenCreateRequest(accessToken, accountID), ).Execute() ``` #### Response fields  string A token that can be sent to Stripe for use in making API calls to Plaid string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "stripe_bank_account_token": "btok_5oEetfLzPklE1fwJZ7SG", "request_id": "xrQNYZ7Zoh6R7gV" } ``` --- # API - Assets | Plaid Docs Assets  ======= #### API reference for Assets endpoints and webhooks  Create, delete, retrieve and share Asset Reports with information about a user's assets and transactions. For how-to guidance on Asset Reports, see the [Assets documentation](https://plaid.com/docs/assets/index.html.md) . All the endpoints on this page are also compatible with [Financial Insights Reports (UK only)](https://plaid.com/docs/assets/index.html.md#financial-insights-reports-uk-only) and will automatically operate on Financial Insights Reports instead of Asset Reports if the Financial Insights Report add-on has been enabled. | Endpoints | | | --- | --- | | [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) | Create an Asset Report | | [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) | Get an Asset Report | | [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) | Get a PDF Asset Report | | [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) | Create an updated Asset Report | | [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) | Filter unneeded accounts from an Asset Report | | [/asset\_report/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportremove) | Delete an asset report | | [/asset\_report/audit\_copy/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copycreate) | Create an Audit Copy of an Asset Report for sharing | | [/asset\_report/audit\_copy/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copyremove) | Delete an Audit Copy of an Asset Report | | [/credit/relay/create](https://plaid.com/docs/api/products/assets/index.html.md#creditrelaycreate) | Create a relay token of an Asset Report for sharing (beta) | | [/credit/relay/get](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayget) | Retrieve the report associated with a relay token (beta) | | [/credit/relay/refresh](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayrefresh) | Refresh a report of a relay token (beta) | | [/credit/relay/remove](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayremove) | Delete a relay token (beta) | | Webhooks | | | --- | --- | | [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) | Asset Report generation has completed | | [ERROR](https://plaid.com/docs/api/products/assets/index.html.md#error) | Asset Report generation has failed | ### Endpoints  \=\*=\*=\*= #### /asset\_report/create  #### Create an Asset Report  The [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) endpoint initiates the process of creating an Asset Report, which can then be retrieved by passing the `asset_report_token` return value to the [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) or [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) endpoints. The Asset Report takes some time to be created and is not available immediately after calling [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) . The exact amount of time to create the report will vary depending on how many days of history are requested and will typically range from a few seconds to about one minute. When the Asset Report is ready to be retrieved using [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) or [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) , Plaid will fire a `PRODUCT_READY` webhook. For full details of the webhook schema, see [Asset Report webhooks](https://plaid.com/docs/api/products/assets/index.html.md#webhooks) . The [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) endpoint creates an Asset Report at a moment in time. Asset Reports are immutable. To get an updated Asset Report, use the [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) endpoint. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. \[string\] An array of access tokens corresponding to the Items that will be included in the report. The `assets` product must have been initialized for the Items during link; the Assets product cannot be added after initialization. Min items: `1` Max items: `99` required, integer The maximum integer number of days of history to include in the Asset Report. If using Fannie Mae Day 1 Certainty, `days_requested` must be at least 61 for new originations or at least 31 for refinancings. An Asset Report requested with "Additional History" (that is, with more than 61 days of transaction history) will incur an Additional History fee. Maximum: `731` Minimum: `0` object An optional object to filter `/asset_report/create` results. If provided, must be non-`null`. The optional `user` object is required for the report to be eligible for Fannie Mae's Day 1 Certainty program. string Client-generated identifier, which can be used by lenders to track loan applications. string URL to which Plaid will send Assets webhooks, for example when the requested Asset Report is ready. Format: `url` \[string\] A list of add-ons that should be included in the Asset Report. When Fast Assets is requested, Plaid will create two versions of the Asset Report: the Fast Asset Report, which will contain only Identity and Balance information, and the Full Asset Report, which will also contain Transactions information. A `PRODUCT_READY` webhook will be fired for each Asset Report when it is ready, and the `report_type` field will indicate whether the webhook is firing for the `full` or `fast` Asset Report. To retrieve the Fast Asset Report, call `/asset_report/get` with `fast_report` set to `true`. There is no additional charge for using Fast Assets. To create a Fast Asset Report, Plaid must successfully retrieve both Identity and Balance data; if Plaid encounters an error obtaining this data, the Fast Asset Report will not be created. However, as long as Plaid can obtain Transactions data, the Full Asset Report will still be available. When Investments is requested, `investments` must be specified in the `optional_products` array when initializing Link. Possible values: `investments`, `fast_assets` object The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The `first_name`, `last_name`, and `ssn` fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program. string An identifier you determine and submit for the user. string The user's first name. Required for the Fannie Mae Day 1 Certainty™ program. string The user's middle name string The user's last name. Required for the Fannie Mae Day 1 Certainty™ program. string The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program. Format: "ddd-dd-dddd" string The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis. string The user's email address. boolean If set to false, only 1 item must be healthy at the time of report creation. The default value is true, which would require all items to be healthy at the time of report creation. Default: `true` ```python # access_tokens is a list of Item access tokens. # Note that the assets product must be enabled for all Items. # All fields on the options object are optional. request = AssetReportCreateRequest( access_tokens=[access_token], days_requested=90, options=AssetReportCreateRequestOptions( webhook='https://www.example.com', client_report_id='123', user=AssetReportUser( client_user_id='7f57eb3d2a9j6480121fx361', first_name='Jane', middle_name='Leah', last_name='Doe', ssn='123-45-6789', phone_number='(555) 123-4567', email='jane.doe@example.com', ) ) ) response = client.asset_report_create(request) asset_report_id = response['asset_report_id'] asset_report_token = response['asset_report_token'] ``` ```ruby # access_tokens is a list of Item access tokens. # Note that the assets product must be enabled for all Items. # All fields on the options Hash are optional. options = { client_report_id: '123', webhook: 'https://www.example.com', user: { client_user_id: '7f57eb3d2a9j6480121fx361', first_name: 'Jane', middle_name: 'Leah', last_name: 'Doe', ssn: '123-45-6789', phone_number: '(555) 123-4567', email: 'jane.doe@example.com', }, } request = Plaid::AssetReportCreateRequest.new( { access_tokens: [access_token], days_requested: 90, options: options } ) response = client.asset_report_create(request) asset_report_id = response.asset_report_id asset_report_token = response.asset_report_token ``` ```go response, _, err := client.PlaidApi.AssetReportCreate(ctx).AssetReportCreateRequest( *plaid.NewAssetReportCreateRequest( []string{accessToken}, // list of access tokens 90, // number of days requested ), ).Execute() ``` ```bash curl -X POST https://sandbox.plaid.com/asset_report/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_tokens": [access_tokens], "days_requested": 90, "options": { "client_report_id": "123", "webhook": "https://www.example.com", "user": { "client_user_id": "userid123", "first_name": "Jane", "middle_name": "Leah", "last_name": "Doe", "ssn": "123-45-6789", "phone_number": "(555) 123-4567", "email": "jane.doe@example.com" } } }' ``` ```java // access_tokens is an array of Item access tokens. // Note that the assets product must be enabled for all Items. // All fields on the options object are optional. AssetReportCreateRequest assetReportCreateRequest = new AssetReportCreateRequest() .accessTokens(access_tokens) .daysRequested(90); AssetReportUser assetReportUser = new AssetReportUser() .firstName("Alberta") .middleName("Bobbeth") .lastName("Charleson"); AssetReportCreateRequestOptions assetReportCreateOptions = new AssetReportCreateRequestOptions() .user(assetReportUser) .webhook(webhookUrl); assetReportCreateRequest.options(assetReportCreateOptions); Response response = client .assetReportCreate(assetReportCreateRequest) .execute(); String assetReportId = response.body().getAssetReportId(); String assetReportToken = response.body().getAssetReportToken(); ``` ```node const daysRequested = 90; const options = { client_report_id: '123', webhook: 'https://www.example.com', user: { client_user_id: '7f57eb3d2a9j6480121fx361', first_name: 'Jane', middle_name: 'Leah', last_name: 'Doe', ssn: '123-45-6789', phone_number: '(555) 123-4567', email: 'jane.doe@example.com', }, }; const request: AssetReportCreateRequest = { access_tokens: [accessToken], days_requested, options, }; // accessTokens is an array of Item access tokens. // Note that the assets product must be enabled for all Items. // All fields on the options object are optional. try { const response = await plaidClient.assetReportCreate(request); const assetReportId = response.data.asset_report_id; const assetReportToken = response.data.asset_report_token; } catch (error) { // handle error } ``` #### Response fields  string A token that can be provided to endpoints such as `/asset_report/get` or `/asset_report/pdf/get` to fetch or update an Asset Report. string A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a", "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb", "request_id": "Iam3b" } ``` \=\*=\*=\*= #### /asset\_report/get  #### Retrieve an Asset Report  The [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) endpoint retrieves the Asset Report in JSON format. Before calling [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) , you must first create the Asset Report using [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) (or filter an Asset Report using [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) ) and then wait for the [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) webhook to fire, indicating that the Report is ready to be retrieved. By default, an Asset Report includes transaction descriptions as returned by the bank, as opposed to parsed and categorized by Plaid. You can also receive cleaned and categorized transactions, as well as additional insights like merchant name or location information. We call this an Asset Report with Insights. An Asset Report with Insights provides transaction category, location, and merchant information in addition to the transaction strings provided in a standard Asset Report. To retrieve an Asset Report with Insights, call [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) endpoint with `include_insights` set to `true`. For latency-sensitive applications, you can optionally call [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) with `options.add_ons` set to `["fast_assets"]`. This will cause Plaid to create two versions of the Asset Report: one with only current and available balance and identity information, and then later on the complete Asset Report. You will receive separate webhooks for each version of the Asset Report. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A token that can be provided to endpoints such as `/asset_report/get` or `/asset_report/pdf/get` to fetch or update an Asset Report. boolean `true` if you would like to retrieve the Asset Report with Insights, `false` otherwise. This field defaults to `false` if omitted. Default: `false` boolean `true` to fetch "fast" version of asset report. Defaults to false if omitted. Can only be used if `/asset_report/create` was called with `options.add_ons` set to `["fast_assets"]`. Default: `false` object An optional object to filter or add data to `/asset_report/get` results. If provided, must be non-`null`. integer The maximum number of days of history to include in the Asset Report. Maximum: `731` Minimum: `0` ```go request := plaid.NewAssetReportGetRequest() request.SetAssetReportToken(assetReportToken) response, _, err := client.PlaidApi.AssetReportGet(ctx).AssetReportGetRequest( *request, ).Execute() ``` ```bash curl -X POST https://sandbox.plaid.com/asset_report/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "asset_report_token": String, "include_insights": Boolean }' ``` ```python # asset_report_token is the token from the AssetReport.create response. try: request = AssetReportGetRequest(asset_report_token=asset_report_token) response = client.asset_report_get(request) report = response['report'] except plaid.ApiException as e: if e.code == 'PRODUCT_NOT_READY': # Asset report is not ready yet. Try again later. else: # Handle error. ``` ```java // assetReportToken is the token from the AssetReportCreateRequest response. AssetReportGetRequest request = new AssetReportGetRequest() .includeInsights(true) .assetReportToken(assetReportToken); Response response = client().assetReportGet(request).execute(); if (response.isSuccessful()){ AssetReport report = response.body().getReport(); } else { try{ Gson gson = new Gson(); Error error = gson.fromJson(response.errorBody().string(), Error.class); if (error.getErrorCode().equals("PRODUCT_NOT_READY")){ // Asset report is not ready yet. Try again later } } catch (Exception e) { // handle error } } ``` ```ruby # asset_report_token is the token from the AssetReport.create response. begin request = Plaid::AssetReportGetRequest.new({ asset_report_token: asset_report_token }) response = client.asset_report_get(request) report = response.report rescue Plaid::ApiError => e json_response = JSON.parse(e.response_body) if json_response['error_code'] == 'PRODUCT_NOT_READY' # Asset report is not ready yet. Try again later end # handle error ``` ```node const request: AssetReportGetRequest = { asset_report_token: assetReportToken, include_insights: true, }; try { const response = await plaidClient.assetReportGet(request); const assetReportId = response.data.asset_report_id; } catch (error) { if (error.data.error_code == 'PRODUCT_NOT_READY') { // Asset report is not ready yet. Try again later } else { // handle error } } ``` #### Response fields  object An object representing an Asset Report string A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. nullable, object This is a container object for all lending-related insights. This field will be returned only for European customers. nullable, object Risk indicators focus on providing signal on the possibility of a borrower defaulting on their loan repayments by providing data points related to its payment behavior, debt, and other relevant financial information, helping lenders gauge the level of risk involved in a certain operation. nullable, object Insights into bank penalties and fees, including overdraft fees, NSF fees, and other bank-imposed charges. nullable, number The total value of outflow transactions categorized as `BANK_PENALTIES`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of transactions that fall into the `BANK_PENALTIES` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `BANK_PENALTIES` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into the `BANK_PENALTIES` credit category. If there's no available income for the given time period, this field value will be `-1`. Format: `double` nullable, object Insights into gambling-related transactions, including frequency, amounts, and top merchants. nullable, number The total value of transactions that fall into the `GAMBLING` credit category, across all the accounts in the report. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top merchants that the user had the most transactions for in the given time window, in descending order of total spend. If the user has not spent money on any merchants in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `GAMBLING` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `GAMBLING` category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `GAMBLING` category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `GAMBLING` category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `GAMBLING` credit category. If there's no available income for the given time period, this field value will be `-1` Format: `double` nullable, object Insights into loan disbursement transactions received by the user, tracking incoming funds from loan providers. nullable, number The total value of inflow transactions categorized as `LOAN_DISBURSEMENTS`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `LOAN_DISBURSEMENTS` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top service providers that the user had the most transactions for in the given time window, in descending order of total spend. If the user has received money from any provider in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `LOAN_DISBURSEMENTS` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `LOAN_DISBURSEMENTS` category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `LOAN_DISBURSEMENTS` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was received on transactions that fall into the `LOAN_DISBURSEMENTS` credit category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `LOAN_DISBURSEMENTS` credit category. If there's no available income for the given time period, this field value will be `-1`. Format: `double` nullable, object Insights into loan payment transactions made by the user, tracking outgoing payments to loan providers. nullable, number The total value of outflow transactions categorized as `LOAN_PAYMENTS`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top service providers that the user had the most transactions for in the given time window, in descending order of total spend. If the user has not spent money on any provider in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `LOAN_PAYMENTS` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `LOAN_PAYMENTS` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `LOAN_PAYMENTS` credit category. If there's no available income for the giving time period, this field value will be `-1` Format: `double` nullable, object Insights into negative balance occurrences, including frequency, duration, and minimum balance details. nullable, integer The number of days since the last transaction that caused any account in the report to have a negative balance. This value is inclusive of the date of the last negative balance, meaning that if the last negative balance occurred today, this value will be `0`. nullable, integer The number of aggregated days that the accounts in the report has had a negative balance within the given time window. nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] The summary of the negative balance occurrences for this account. If the user has not had a negative balance in the account in the given time window, this list will be empty. nullable, string The date of the first transaction that caused the account to have a negative balance. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` nullable, string The date of the last transaction that caused the account to have a negative balance. The date will be returned in an ISO 8601 format (YYYY-MM-DD). This date is inclusive, meaning that this was the last date that the account had a negative balance. Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Affordability insights focus on providing signal on the ability of a borrower to repay their loan without experiencing financial strain. It provides insights on factors such a user's monthly income and expenses, disposable income, average expenditure, etc., helping lenders gauge the level of affordability of a borrower. nullable, object Comprehensive analysis of spending patterns, categorizing expenses into essential, non-essential, and other categories. nullable, object Net cash flow for the period (inflows minus outflows), including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Insights into unusually large transactions that exceed typical spending patterns for the account. nullable, integer The total number of transactions whose value is above the threshold of normal amounts for a given account. nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Up to 3 top categories of expenses in this group. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Comprehensive income analysis including total income, income excluding transfers, and inbound transfer amounts. nullable, object The total amount of all income transactions in the given time period. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Income excluding account transfer transactions for the period, including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Sum of inbound transfer transactions for the period, including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string An identifier you determine and submit for the Asset Report. string The date and time when the Asset Report was created, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (e.g. "2018-04-12T03:32:11Z"). Format: `date-time` number The duration of transaction history you requested object The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The `first_name`, `last_name`, and `ssn` fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program. nullable, string An identifier you determine and submit for the user. nullable, string The user's first name. Required for the Fannie Mae Day 1 Certainty™ program. nullable, string The user's middle name nullable, string The user's last name. Required for the Fannie Mae Day 1 Certainty™ program. nullable, string The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program. Format: "ddd-dd-dddd" nullable, string The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis. nullable, string The user's email address. \[object\] Data returned by Plaid about each of the Items included in the Asset Report. string The `item_id` of the Item associated with this webhook, warning, or error string The full financial institution name associated with the Item. string The id of the financial institution associated with the Item. string The date and time when this Item’s data was last retrieved from the financial institution, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` \[object\] Data about each of the accounts open on the Item. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get`. nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get`; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, number The total amount of borrowed funds in the account, as determined by the financial institution. For investment-type accounts, the margin balance is the total value of borrowed assets in the account, as presented by the institution. This is commonly referred to as margin or a loan. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the oldest acceptable balance when making a request to `/accounts/balance/get`. This field is only used and expected when the institution is `ins_128026` (Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an `INVALID_REQUEST` error with the code of `INVALID_FIELD` will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See [account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of account types. If the balance that is pulled is older than the given timestamp for Items with this field required, an `INVALID_REQUEST` error with the code of `LAST_UPDATED_DATETIME_OUT_OF_RANGE` will be returned with the most recent timestamp for the requested account contained in the response. Format: `date-time` nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only. `pending_automatic_verification`: The Item is pending automatic verification `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit. `automatically_verified`: The Item has successfully been automatically verified `manually_verified`: The Item has successfully been manually verified `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `database_matched`: The Item has successfully been verified using Plaid's data sources. Note: Database Match is currently a beta feature, please contact your account manager for more information. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items. number The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account. \[object\] Transaction history associated with the account. string The ID of the account in which this transaction occurred. number The settled value of the transaction, denominated in the transaction's currency, as stated in `iso_currency_code` or `unofficial_currency_code`. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. Format: `double` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string The string returned by the financial institution to describe the transaction. nullable, \[string\] A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) . This field will only appear in an Asset Report with Insights. nullable, string The ID of the category to which this transaction belongs. For a full list of categories, see [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) . This field will only appear in an Asset Report with Insights. nullable, object Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. See the [taxonomy csv file](https://plaid.com/documents/credit-category-taxonomy.csv) for a full list of credit categories. string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string The check number of the transaction. This field is only populated for check transactions. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). Format: `date` nullable, string The date on which the transaction took place, in IS0 8601 format. object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. deprecated, string The merchant name or transaction description. This is a legacy field that is no longer maintained. For merchant name, use the `merchant_name` field. For description, use the `original_description` field. This field will only appear in an Asset Report with Insights. nullable, string The merchant name, as enriched by Plaid. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be `null`. object Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be `null`. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, the `payment_meta` key will always appear, but no data elements are guaranteed. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The transaction reference number supplied by the financial institution. nullable, string The ACH PPD ID for the payer. nullable, string For transfers, the party that is receiving the transaction. nullable, string The party initiating a wire transfer. Will be `null` if the transaction is not a wire transfer. nullable, string For transfers, the party that is paying the transaction. nullable, string The type of transfer, e.g. 'ACH' nullable, string The name of the payment processor nullable, string The payer-supplied description of the transfer. boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. nullable, string The ID of a posted transaction's associated pending transaction, where applicable. nullable, string The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. string `digital:` transactions that took place online. `place:` transactions that were made at a physical location. `special:` transactions that relate to banks, e.g. fees or deposits. `unresolved:` transactions that do not fit into the other three types. Possible values: `digital`, `place`, `special`, `unresolved` object A set of fields describing the investments data on an account. \[object\] Quantities and values of securities held in the investment account. Map to the `securities` array for security details. string The Plaid `account_id` associated with the holding. string The Plaid `security_id` associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The `security_id` for the same security will typically be the same across different institutions, but this is not guaranteed. The `security_id` does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. nullable, string The holding's trading symbol for publicly traded holdings, and otherwise a short identifier if available. number The last price given by the institution for this security. Format: `double` nullable, string The date at which `institution_price` was current. Format: `date` number The value of the holding, as reported by the institution. Format: `double` nullable, number The original total value of the holding. This field is calculated by Plaid as the sum of the purchase price of all of the shares in the holding. Format: `double` number The total quantity of the asset held, as reported by the financial institution. If the security is an option, `quantity` will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts. Format: `double` nullable, string The ISO-4217 currency code of the holding. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the holding. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. \[object\] Details of specific securities held in on the investment account. string A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the `security_id` is case sensitive. The `security_id` may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. nullable, string A descriptive name for the security, suitable for display. nullable, string The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available. nullable, string The security type of the holding. Valid security types are: `cash`: Cash, currency, and money market funds `cryptocurrency`: Digital or virtual currencies `derivative`: Options, warrants, and other derivative instruments `equity`: Domestic and foreign equities `etf`: Multi-asset exchange-traded investment funds `fixed income`: Bonds and certificates of deposit (CDs) `loan`: Loans and loan receivables `mutual fund`: Open- and closed-end vehicles pooling funds of multiple investors `other`: Unknown or other investment types \[object\] Transaction history on the investment account. string The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the `investment_transaction_id` is case sensitive. string The `account_id` of the account against which this transaction posted. nullable, string The `security_id` to which this transaction is related. string The [ISO 8601](https://wikipedia.org/wiki/ISO_8601) posting date for the transaction. Format: `date` string The institution’s description of the transaction. number The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions. Format: `double` number The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with [equities](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-type) . Format: `double` number The value of the vested holdings as reported by the institution. Format: `double` number The complete value of the transaction. Positive values when cash is debited, e.g. purchases of stock; negative values when cash is credited, e.g. sales of stock. Treatment remains the same for cash-only movements unassociated with securities. Format: `double` number The price of the security at which this transaction occurred. Format: `double` nullable, number The combined value of all fees applied to this transaction Format: `double` string Value is one of the following: `buy`: Buying an investment `sell`: Selling an investment `cancel`: A cancellation of a pending transaction `cash`: Activity that modifies a cash position `fee`: A fee on the account `transfer`: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer For descriptions of possible transaction types and subtypes, see the [Investment transaction types schema](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Possible values: `buy`, `sell`, `cancel`, `cash`, `fee`, `transfer` string For descriptions of possible transaction types and subtypes, see the [Investment transaction types schema](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Possible values: `account fee`, `adjustment`, `assignment`, `buy`, `buy to cover`, `contribution`, `deposit`, `distribution`, `dividend`, `dividend reinvestment`, `exercise`, `expire`, `fund fee`, `interest`, `interest receivable`, `interest reinvestment`, `legal fee`, `loan payment`, `long-term capital gain`, `long-term capital gain reinvestment`, `management fee`, `margin expense`, `merger`, `miscellaneous fee`, `non-qualified dividend`, `non-resident tax`, `pending credit`, `pending debit`, `qualified dividend`, `rebalance`, `return of principal`, `request`, `sell`, `sell short`, `send`, `short-term capital gain`, `short-term capital gain reinvestment`, `spin off`, `split`, `stock distribution`, `tax`, `tax withheld`, `trade`, `transfer`, `transfer fee`, `trust fee`, `unqualified gain`, `withdrawal` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the holding. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. \[object\] Data returned by the financial institution about the account owner or owners.For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same `owner` object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the `owners` object is not returned, and instead identity information is returned in the top level `identity` object. For more details, see [Plaid API versioning](https://plaid.com/docs/api/versioning/index.html.md#version-2019-05-29) \[string\] A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's `names` array. \[object\] A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The phone number. boolean When `true`, identifies the phone number as the primary number on an account. string The type of phone number. Possible values: `home`, `work`, `office`, `mobile`, `mobile1`, `other` \[object\] A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The email address. boolean When `true`, identifies the email address as the primary email on an account. string The type of email account as described by the financial institution. Possible values: `primary`, `secondary`, `other` \[object\] Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. object Data about the components comprising an address. nullable, string The full city name nullable, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code boolean When `true`, identifies the address as the primary address on an account. nullable, string How an asset is owned. `association`: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. `individual`: Ownership by an individual. `joint`: Joint ownership by multiple parties. `trust`: Ownership by a revocable or irrevocable trust. Possible values: `null`, `individual`, `joint`, `association`, `trust` \[object\] Calculated data about the historical balances on the account. Available for `credit` and `depository` type accounts. string The date of the calculated historical balance, in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD) Format: `date` number The total amount of funds in the account, calculated from the `current` balance in the `balance` object by subtracting inflows and adding back outflows according to the posted date of each transaction. If the account has any pending transactions, historical balance amounts on or after the date of the earliest pending transaction may differ if retrieved in subsequent Asset Reports as a result of those pending transactions posting. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the balance. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object This is a container object for all lending-related insights. This field will be returned only for European customers. nullable, object Risk indicators focus on providing signal on the possibility of a borrower defaulting on their loan repayments by providing data points related to its payment behavior, debt, and other relevant financial information, helping lenders gauge the level of risk involved in a certain operation. nullable, object Insights into bank penalties and fees, including overdraft fees, NSF fees, and other bank-imposed charges. nullable, number The total value of outflow transactions categorized as `BANK_PENALTIES`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of transactions that fall into the `BANK_PENALTIES` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `BANK_PENALTIES` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into the `BANK_PENALTIES` credit category. If there's no available income for the given time period, this field value will be `-1`. Format: `double` nullable, object Insights into gambling-related transactions, including frequency, amounts, and top merchants. nullable, number The total value of transactions that fall into the `GAMBLING` credit category, across all the accounts in the report. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top merchants that the user had the most transactions for in the given time window, in descending order of total spend. If the user has not spent money on any merchants in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `GAMBLING` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `GAMBLING` category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `GAMBLING` category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `GAMBLING` category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `GAMBLING` credit category. If there's no available income for the given time period, this field value will be `-1` Format: `double` nullable, object Insights into loan disbursement transactions received by the user, tracking incoming funds from loan providers. nullable, number The total value of inflow transactions categorized as `LOAN_DISBURSEMENTS`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `LOAN_DISBURSEMENTS` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top service providers that the user had the most transactions for in the given time window, in descending order of total spend. If the user has received money from any provider in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `LOAN_DISBURSEMENTS` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `LOAN_DISBURSEMENTS` category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `LOAN_DISBURSEMENTS` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was received on transactions that fall into the `LOAN_DISBURSEMENTS` credit category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `LOAN_DISBURSEMENTS` credit category. If there's no available income for the given time period, this field value will be `-1`. Format: `double` nullable, object Insights into loan payment transactions made by the user, tracking outgoing payments to loan providers. nullable, number The total value of outflow transactions categorized as `LOAN_PAYMENTS`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top service providers that the user had the most transactions for in the given time window, in descending order of total spend. If the user has not spent money on any provider in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `LOAN_PAYMENTS` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `LOAN_PAYMENTS` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `LOAN_PAYMENTS` credit category. If there's no available income for the giving time period, this field value will be `-1` Format: `double` nullable, object Insights into negative balance occurrences, including frequency, duration, and minimum balance details. nullable, integer The number of days since the last transaction that caused any account in the report to have a negative balance. This value is inclusive of the date of the last negative balance, meaning that if the last negative balance occurred today, this value will be `0`. nullable, integer The number of aggregated days that the accounts in the report has had a negative balance within the given time window. nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] The summary of the negative balance occurrences for this account. If the user has not had a negative balance in the account in the given time window, this list will be empty. nullable, string The date of the first transaction that caused the account to have a negative balance. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` nullable, string The date of the last transaction that caused the account to have a negative balance. The date will be returned in an ISO 8601 format (YYYY-MM-DD). This date is inclusive, meaning that this was the last date that the account had a negative balance. Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Affordability insights focus on providing signal on the ability of a borrower to repay their loan without experiencing financial strain. It provides insights on factors such a user's monthly income and expenses, disposable income, average expenditure, etc., helping lenders gauge the level of affordability of a borrower. nullable, object Comprehensive analysis of spending patterns, categorizing expenses into essential, non-essential, and other categories. nullable, object Net cash flow for the period (inflows minus outflows), including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Insights into unusually large transactions that exceed typical spending patterns for the account. nullable, integer The total number of transactions whose value is above the threshold of normal amounts for a given account. nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Up to 3 top categories of expenses in this group. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Comprehensive income analysis including total income, income excluding transfers, and inbound transfer amounts. nullable, object The total amount of all income transactions in the given time period. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Income excluding account transfer transactions for the period, including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Sum of inbound transfer transactions for the period, including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] If the Asset Report generation was successful but identity information cannot be returned, this array will contain information about the errors causing identity information to be missing string The warning type, which will always be `ASSET_REPORT_WARNING` string The warning code identifies a specific kind of warning. `OWNERS_UNAVAILABLE` indicates that account-owner information is not available.`INVESTMENTS_UNAVAILABLE` indicates that Investments specific information is not available. `TRANSACTIONS_UNAVAILABLE` indicates that transactions information associated with Credit and Depository accounts are unavailable. Possible values: `OWNERS_UNAVAILABLE`, `INVESTMENTS_UNAVAILABLE`, `TRANSACTIONS_UNAVAILABLE` nullable, object An error object and associated `item_id` used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The `item_id` of the Item associated with this webhook, warning, or error string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "report": { "asset_report_id": "028e8404-a013-4a45-ac9e-002482f9cafc", "client_report_id": "client_report_id_1221", "date_generated": "2023-03-30T18:27:37Z", "days_requested": 90, "items": [ { "accounts": [ { "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8", "balances": { "available": 43200, "current": 43200, "limit": null, "margin_loan_amount": null, "iso_currency_code": "USD", "unofficial_currency_code": null }, "days_available": 90, "historical_balances": [ { "current": 49050, "date": "2023-03-29", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 49050, "date": "2023-03-28", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 49050, "date": "2023-03-27", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 49050, "date": "2023-03-26", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 49050, "date": "2023-03-25", "iso_currency_code": "USD", "unofficial_currency_code": null } ], "mask": "4444", "name": "Plaid Money Market", "official_name": "Plaid Platinum Standard 1.85% Interest Money Market", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "region": "NY", "street": "2992 Cameron Road", "postal_code": "14236" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "region": "CA", "street": "2493 Leisure Lane", "postal_code": "93405-2255" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholder1@example.com", "primary": false, "type": "secondary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "+1 111-555-3333", "primary": false, "type": "home" }, { "data": "+1 111-555-4444", "primary": false, "type": "work" }, { "data": "+1 111-555-5555", "primary": false, "type": "mobile" } ] } ], "ownership_type": null, "subtype": "money market", "transactions": [ { "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8", "amount": 5850, "date": "2023-03-30", "iso_currency_code": "USD", "original_description": "ACH Electronic CreditGUSTO PAY 123456", "pending": false, "transaction_id": "gGQgjoeyqBF89PND6K14Sow1wddZBmtLomJ78", "unofficial_currency_code": null } ], "type": "depository" }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "balances": { "available": 100, "current": 110, "limit": null, "margin_loan_amount": null, "iso_currency_code": "USD", "unofficial_currency_code": null }, "days_available": 90, "historical_balances": [ { "current": 110, "date": "2023-03-29", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": -390, "date": "2023-03-28", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": -373.67, "date": "2023-03-27", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": -284.27, "date": "2023-03-26", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": -284.27, "date": "2023-03-25", "iso_currency_code": "USD", "unofficial_currency_code": null } ], "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "region": "NY", "street": "2992 Cameron Road", "postal_code": "14236" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "region": "CA", "street": "2493 Leisure Lane", "postal_code": "93405-2255" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholder1@example.com", "primary": false, "type": "secondary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "+1 111-555-3333", "primary": false, "type": "home" }, { "data": "+1 111-555-4444", "primary": false, "type": "work" }, { "data": "+1 111-555-5555", "primary": false, "type": "mobile" } ] } ], "ownership_type": null, "subtype": "checking", "transactions": [ { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": 89.4, "date": "2023-03-27", "iso_currency_code": "USD", "original_description": "SparkFun", "pending": false, "transaction_id": "4zBRq1Qem4uAPnoyKjJNTRQpQddM4ztlo1PLD", "unofficial_currency_code": null }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": 12, "date": "2023-03-28", "iso_currency_code": "USD", "original_description": "McDonalds #3322", "pending": false, "transaction_id": "dkjL41PnbKsPral79jpxhMWdW55gkPfBkWpRL", "unofficial_currency_code": null }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": 4.33, "date": "2023-03-28", "iso_currency_code": "USD", "original_description": "Starbucks", "pending": false, "transaction_id": "a84ZxQaWDAtDL3dRgmazT57K7jjN3WFkNWMDy", "unofficial_currency_code": null }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": -500, "date": "2023-03-29", "iso_currency_code": "USD", "original_description": "United Airlines **** REFUND ****", "pending": false, "transaction_id": "xG9jbv3eMoFWepzB7wQLT3LoLggX5Duy1Gbe5", "unofficial_currency_code": null } ], "type": "depository" } ], "date_last_updated": "2023-03-30T18:25:26Z", "institution_id": "ins_109508", "institution_name": "First Platypus Bank", "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7" } ], "user": { "client_user_id": "uid_40332", "email": "abcharleston@example.com", "first_name": "Anna", "last_name": "Charleston", "middle_name": "B", "phone_number": "1-415-867-5309", "ssn": "111-22-1234" } }, "request_id": "GVzMdiDd8DDAQK4", "warnings": [] } ``` \=\*=\*=\*= #### /asset\_report/pdf/get  #### Retrieve a PDF Asset Report  The [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) endpoint retrieves the Asset Report in PDF format. Before calling [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) , you must first create the Asset Report using [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) (or filter an Asset Report using [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) ) and then wait for the [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) webhook to fire, indicating that the Report is ready to be retrieved. The response to [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) is the PDF binary data. The `request_id` is returned in the `Plaid-Request-ID` header. [View a sample PDF Asset Report](https://plaid.com/documents/sample-asset-report.pdf) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string A token that can be provided to endpoints such as `/asset_report/get` or `/asset_report/pdf/get` to fetch or update an Asset Report. object An optional object to filter or add data to `/asset_report/get` results. If provided, must be non-`null`. integer The maximum integer number of days of history to include in the Asset Report. Maximum: `731` Minimum: `0` ```java AssetReportPDFGetRequest assetReportPdfGet = new AssetReportPDFGetRequest() .assetReportToken(assetReportToken); Response response = client() .assetReportPdfGet(assetReportPdfGet) .execute(); byte[] pdf = response.body().bytes(); ``` ```go response, _, err := client.PlaidApi.AssetReportPdfGet(ctx).AssetReportPDFGetRequest( *plaid.NewAssetReportPDFGetRequest("ASSET_REPORT_TOKEN"), ).Execute() ``` ```node try { const request: AssetReportPDFGetRequest = { asset_report_token: assetReportToken, }; const response = await plaidClient.assetReportPdfGet(request, { responseType: 'arraybuffer', }); const pdf = response.buffer.toString('base64'); } catch (error) { // handle error } ``` ```python request = AssetReportPDFGetRequest(asset_report_token=asset_report_token) pdf = client.asset_report_pdf_get(request) ``` ```ruby request = Plaid::AssetReportPDFGetRequest.new({ asset_report_token: asset_report_token }) asset_report_pdf = client.asset_report_pdf_get(request) ``` ```bash curl -X POST https://sandbox.plaid.com/asset_report/pdf/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "asset_report_token": String }' \ -o 'asset_report.pdf' ``` ##### Response  This endpoint returns binary PDF data. [View a sample Asset Report PDF](https://plaid.com/documents/sample-asset-report.pdf) . [View a sample Financial Insights Report (UK/EU only) PDF](https://plaid.com/documents/sample-financial-insights-report.pdf) . \=\*=\*=\*= #### /asset\_report/refresh  #### Refresh an Asset Report  An Asset Report is an immutable snapshot of a user's assets. In order to "refresh" an Asset Report you created previously, you can use the [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) endpoint to create a new Asset Report based on the old one, but with the most recent data available. The new Asset Report will contain the same Items as the original Report, as well as the same filters applied by any call to [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) . By default, the new Asset Report will also use the same parameters you submitted with your original [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) request, but the original `days_requested` value and the values of any parameters in the `options` object can be overridden with new values. To change these arguments, simply supply new values for them in your request to [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) . Submit an empty string ("") for any previously-populated fields you would like set as empty. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The `asset_report_token` returned by the original call to `/asset_report/create` integer The maximum number of days of history to include in the Asset Report. Must be an integer. If not specified, the value from the original call to `/asset_report/create` will be used. Minimum: `0` Maximum: `731` object An optional object to filter `/asset_report/refresh` results. If provided, cannot be `null`. If not specified, the `options` from the original call to `/asset_report/create` will be used. string Client-generated identifier, which can be used by lenders to track loan applications. string URL to which Plaid will send Assets webhooks, for example when the requested Asset Report is ready. Format: `url` object The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The `first_name`, `last_name`, and `ssn` fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program. string An identifier you determine and submit for the user. string The user's first name. Required for the Fannie Mae Day 1 Certainty™ program. string The user's middle name string The user's last name. Required for the Fannie Mae Day 1 Certainty™ program. string The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program. Format: "ddd-dd-dddd" string The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis. string The user's email address. ```ruby options = { client_report_id: '123', webhook: 'https://www.example.com', user: { client_user_id: '7f57eb3d2a9j6480121fx361', first_name: 'Jane', middle_name: 'Leah', last_name: 'Doe', ssn: '123-45-6789', phone_number: '(555) 123-4567', email: 'jane.doe@example.com' } } request = Plaid::AssetReportRefreshRequest.new( { asset_report_token: asset_report_token, days_requested: 90, options: options } ) response = client.asset_report_refresh(request) asset_report_id = response.asset_report_id asset_report_token = response.asset_report_token ``` ```bash curl -X POST https://sandbox.plaid.com/asset_report/refresh \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "asset_report_token": "${ASSET_REPORT_TOKEN}", "days_requested": 90, "options": { "client_report_id": "123", "webhook": "https://www.example.com", "user": { "client_user_id": "userid123", "first_name": "Jane", "middle_name": "Leah", "last_name": "Doe", "ssn": "123-45-6789", "phone_number": "(555) 123-4567", "email": "jane.doe@example.com" } } }' ``` ```python request = AssetReportRefreshRequest( asset_report_token=asset_report_token, days_requested=90 ) response = client.asset_report_refresh(request) asset_report_id = response['asset_report_id'] asset_report_token = response['asset_report_token'] ``` ```java AssetReportUser assetReportUser = new AssetReportUser() .lastName("newLastName"); AssetReportRefreshRequestOptions options = new AssetReportRefreshRequestOptions() .user(assetReportUser); AssetReportRefreshRequest request = new AssetReportRefreshRequest() .options(options) .assetReportToken(assetReportToken); Response response = client() .assetReportRefresh(request) .execute(); String assetReportId = response.body().getAssetReportId(); String assetReportToken = response.body().getAssetReportToken(); ``` ```node const request: AssetReportRefreshRequest = { asset_report_token: assetReportToken, daysRequested: 90, options: { client_report_id: '123', webhook: 'https://www.example.com', user: { client_user_id: '7f57eb3d2a9j6480121fx361', first_name: 'Jane', middle_name: 'Leah', last_name: 'Doe', ssn: '123-45-6789', phone_number: '(555) 123-4567', email: 'jane.doe@example.com', }, }, }; try { const response = await plaidClient.assetReportRefresh(request); const assetReportId = response.data.asset_report_id; } catch (error) { // handle error } ``` ```go response, _, err := client.PlaidApi.AssetReportRefresh(ctx).AssetReportRefreshRequest( *plaid.NewAssetReportRefreshRequest("ASSET_REPORT_TOKEN"), ).Execute() ``` #### Response fields  string A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. string A token that can be provided to endpoints such as `/asset_report/get` or `/asset_report/pdf/get` to fetch or update an Asset Report. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0", "asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398", "request_id": "NBZaq" } ``` \=\*=\*=\*= #### /asset\_report/filter  #### Filter Asset Report  By default, an Asset Report will contain all of the accounts on a given Item. In some cases, you may not want the Asset Report to contain all accounts. For example, you might have the end user choose which accounts are relevant in Link using the Account Select view, which you can enable in the dashboard. Or, you might always exclude certain account types or subtypes, which you can identify by using the [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint. To narrow an Asset Report to only a subset of accounts, use the [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) endpoint. To exclude certain Accounts from an Asset Report, first use the [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) endpoint to create the report, then send the `asset_report_token` along with a list of `account_ids` to exclude to the [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) endpoint, to create a new Asset Report which contains only a subset of the original Asset Report's data. Because Asset Reports are immutable, calling [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) does not alter the original Asset Report in any way; rather, [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) creates a new Asset Report with a new token and id. Asset Reports created via [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) do not contain new Asset data, and are not billed. Plaid will fire a [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) webhook once generation of the filtered Asset Report has completed. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string A token that can be provided to endpoints such as `/asset_report/get` or `/asset_report/pdf/get` to fetch or update an Asset Report. required, \[string\] The accounts to exclude from the Asset Report, identified by `account_id`. ```node const request: AssetReportFilterRequest = { asset_report_token: assetReportToken, account_ids_to_exclude: ['JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419'], }; try { const response = await plaidClient.assetReportFilter(request); const assetReportId = response.data.asset_report_id; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/asset_report/filter \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "asset_report_token": String, "account_ids_to_exclude": [String] }' ``` ```java AssetReportFilterRequest request = new AssetReportFilterRequest() .assetReportToken(assetReportToken) .accountIdsToExclude(Arrays.asList("JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419")); Response response = client() .assetReportFilter(request) .execute(); String assetReportId = response.body().getAssetReportId(); String assetReportToken = response.body().getAssetReportToken(); ``` ```ruby request = Plaid::AssetReportFilterRequest.new( { asset_report_token: asset_report_token, account_ids_to_exclude: ["JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419"] } ) response = client.asset_report_filter(request) asset_report_id = response.asset_report_id asset_report_token = response.asset_report_token ``` ```python account_ids_to_exclude = ['JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419'] request = AssetReportFilterRequest( asset_report_token=asset_report_token, account_ids_to_exclude=account_ids_to_exclude ) response = client.asset_report_filter(request) asset_report_id = response['asset_report_id'] asset_report_token = response['asset_report_token'] ``` ```go response, _, err := client.PlaidApi.AssetReportFilter(ctx).AssetReportFilterRequest( *plaid.NewAssetReportFilterRequest( "ASSET_REPORT_TOKEN", []string{"ACCOUNT_IDS_TO_EXCLUDE"}, ), ).Execute() ``` #### Response fields  string A token that can be provided to endpoints such as `/asset_report/get` or `/asset_report/pdf/get` to fetch or update an Asset Report. string A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c", "asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9", "request_id": "qEg07" } ``` \=\*=\*=\*= #### /asset\_report/remove  #### Delete an Asset Report  The [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) endpoint allows you to invalidate an `access_token`, meaning you will not be able to create new Asset Reports with it. Removing an Item does not affect any Asset Reports or Audit Copies you have already created, which will remain accessible until you remove them specifically. The [/asset\_report/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportremove) endpoint allows you to remove access to an Asset Report. Removing an Asset Report invalidates its `asset_report_token`, meaning you will no longer be able to use it to access Report data or create new Audit Copies. Removing an Asset Report does not affect the underlying Items, but does invalidate any `audit_copy_tokens` associated with the Asset Report. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string A token that can be provided to endpoints such as `/asset_report/get` or `/asset_report/pdf/get` to fetch or update an Asset Report. ```go response, _, err := client.PlaidApi.AssetReportRemove(ctx).AssetReportRemoveRequest( *plaid.NewAssetReportRemoveRequest( "ASSET_REPORT_TOKEN", ), ).Execute() ``` ```node const request: AssetReportRemoveRequest = { asset_report_token: assetReportToken, }; try { const response = await plaidClient.assetReportRemove(request); const removed = response.data.removed; } catch (error) { // handle error } ``` ```ruby request = Plaid::AssetReportRemoveRequest.new({ asset_report_token: asset_report_token }) response = client.asset_report_remove(request) removed = response.removed ``` ```python request = AssetReportRemoveRequest(asset_report_token=asset_report_token) response = client.asset_report_remove(request) removed = response['removed'] ``` ```java AssetReportRemoveRequest request = new AssetReportRemoveRequest() .assetReportToken(assetReportToken); Response response = client() .assetReportRemove(request) .execute(); boolean removed = response.body().getRemoved(); ``` ```bash curl -X POST https://sandbox.plaid.com/asset_report/remove \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "asset_report_token": String }' ``` #### Response fields  boolean `true` if the Asset Report was successfully removed. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "removed": true, "request_id": "I6zHN" } ``` \=\*=\*=\*= #### /asset\_report/audit\_copy/create  #### Create Asset Report Audit Copy  Plaid can provide an Audit Copy of any Asset Report directly to a participating third party on your behalf. For example, Plaid can supply an Audit Copy directly to the GSEs on your behalf if you participate in Fannie Mae's Day 1 Certainty™ program or utilize Freddie Mac’s Loan Product Advisor® (LPA®) Asset and Income Modeler (AIM). An Audit Copy contains the same underlying data as the Asset Report. To grant access to an Audit Copy, use the [/asset\_report/audit\_copy/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copycreate) endpoint to create an `audit_copy_token` and then pass that token to the third party who needs access. Each third party has its own `auditor_id`, for example `fannie_mae`. You’ll need to create a separate Audit Copy for each third party to whom you want to grant access to the Report. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string A token that can be provided to endpoints such as `/asset_report/get` or `/asset_report/pdf/get` to fetch or update an Asset Report. string The `auditor_id` of the third party with whom you would like to share the Asset Report. ```python # The auditor ID corresponds to the third party with which you want to share # the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'. request = AssetReportAuditCopyCreateRequest( asset_report_token=asset_report_token, auditor_id='fannie_mae' ) response = client.asset_report_audit_copy_create(request) audit_copy_token = response['audit_copy_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/asset_report/audit_copy/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "asset_report_token": String, "auditor_id": String }' ``` ```java // The auditor ID corresponds to the third party with which you want to share // the asset report. For example, Fannie Mae's auditor ID is "fannie_mae". AssetReportAuditCopyCreateRequest request = new AssetReportAuditCopyCreateRequest() .assetReportToken(assetReportToken) .auditorId("fannie_mae"); Response response = client().assetReportAuditCopyCreate(request).execute(); String auditCopyToken = response.body().getAuditCopyToken(); ``` ```ruby # The auditor ID corresponds to the third party with which you want to share # the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'. request = Plaid::AssetReportAuditCopyCreateRequest.new( { asset_report_token: asset_report_token, auditor_id: 'fannie_mae' } ) response = client.asset_report_audit_copy_create(request) audit_copy_token = response.audit_copy_token ``` ```node // The auditor ID corresponds to the third party with which you want to share // the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'. const request: AssetReportAuditCopyCreateRequest = { asset_report_token: createResponse.data.asset_report_token, auditor_id: 'fannie_mae', }; try { const response = await plaidClient.assetReportAuditCopyCreate(request); const auditCopyToken = response.data.audit_copy_token; } catch (error) { // handle error } ``` ```go response, _, err := client.PlaidApi.AssetReportAuditCopyCreate(ctx).AssetReportAuditCopyCreateRequest( *plaid.NewAssetReportAuditCopyCreateRequest( "ASSET_REPORT_TOKEN", "AUDITOR_ID", ), ).Execute() ``` #### Response fields  string A token that can be shared with a third party auditor to allow them to obtain access to the Asset Report. This token should be stored securely. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4", "request_id": "Iam3b" } ``` \=\*=\*=\*= #### /asset\_report/audit\_copy/remove  #### Remove Asset Report Audit Copy  The [/asset\_report/audit\_copy/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copyremove) endpoint allows you to remove an Audit Copy. Removing an Audit Copy invalidates the `audit_copy_token` associated with it, meaning both you and any third parties holding the token will no longer be able to use it to access Report data. Items associated with the Asset Report, the Asset Report itself and other Audit Copies of it are not affected and will remain accessible after removing the given Audit Copy. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The `audit_copy_token` granting access to the Audit Copy you would like to revoke. ```bash curl -X POST https://sandbox.plaid.com/asset_report/audit_copy/remove \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "audit_copy_token": String }' ``` ```python # audit_copy_token is the token from the AssetReport.audit_copy.create response. request = AssetReportAuditCopyRemoveRequest( audit_copy_token=audit_copy_token, ) response = client.asset_report_audit_copy_remove(request) removed = response['removed'] ``` ```node // auditCopyToken is the token from the createAuditCopy response. const request: AssetReportAuditCopyRemoveRequest = { audit_copy_token: auditCopyToken, }; try { const response = await plaidClient.assetReportAuditCopyRemove(request); const removed = response.data.removed; } catch (error) { // handle error } ``` ```ruby # audit_copy_token is the token from the create_audit_copy response. request = Plaid::AssetReportAuditCopyRemoveRequest.new({ audit_copy_token: audit_copy_token }) response = @client.asset_report_audit_copy_remove(request) removed = response.removed ``` ```java // auditCopyToken is the token from the AssetReportCreateAuditCopyRequest // response. AssetReportAuditCopyRemoveRequest request = new AssetReportAuditCopyRemoveRequest() .auditCopyToken(auditCopyToken); Response response = client() .assetReportAuditCopyRemove(request) .execute(); boolean removed = response.body().getRemoved(); ``` ```go response, _, err := client.PlaidApi.AssetReportAuditCopyRemove(ctx).AssetReportAuditCopyRemoveRequest( *plaid.NewAssetReportAuditCopyRemoveRequest( "AUDIT_COPY_TOKEN", ), ).Execute() ``` #### Response fields  boolean `true` if the Audit Copy was successfully removed. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "removed": true, "request_id": "m8MDnv9okwxFNBV" } ``` \=\*=\*=\*= #### /credit/relay/create  #### Create a relay token to share an Asset Report with a partner client  Plaid can share an Asset Report directly with a participating third party on your behalf. The shared Asset Report is the exact same Asset Report originally created in [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) . To grant a third party access to an Asset Report, use the [/credit/relay/create](https://plaid.com/docs/api/products/assets/index.html.md#creditrelaycreate) endpoint to create a `relay_token` and then pass that token to your third party. Each third party has its own `secondary_client_id`; for example, `ce5bd328dcd34123456`. You'll need to create a separate `relay_token` for each third party that needs access to the report on your behalf. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, \[string\] List of report token strings, with at most one token of each report type. Currently only Asset Report token is supported. required, string The `secondary_client_id` is the client id of the third party with whom you would like to share the relay token. string URL to which Plaid will send webhooks when the Secondary Client successfully retrieves an Asset Report by calling `/credit/relay/get`. Format: `url` ```python request = CreditRelayCreateRequest( report_tokens=[asset_report_token], ) response = client.credit_relay_create(request) relay_token = response['relay_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/credit/relay/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "secondary_client_id": "$client_id_from_partner", "report_tokens": []String, }' ``` ```java CreditRelayCreateRequest request = new CreditRelayCreateRequest() .reportTokens(Arrays.asList(assetReportToken)) .secondaryClientId(clientIdFromPartner); Response response = client().creditRelayCreate(request).execute(); String relayToken = response.body().getRelayToken(); ``` ```ruby request = Plaid::CreditRelayCreateRequest.new( { report_tokens: [asset_report_token], secondary_client_id: clientIdFromPartner } ) response = client.credit_relay_create(request) relay_token = response.relay_token ``` ```node const request: CreditRelayCreateRequest = { report_tokens: [createResponse.data.asset_report_token], secondary_client_id: clientIdFromPartner }; try { const response = await plaidClient.creditRelayCreate(request); const relayToken = response.data.relay_token; } catch (error) { // handle error } ``` ```go response, _, err := client.PlaidApi.CreditRelayCreate(ctx).CreditRelayCreateRequest( *plaid.NewCreditRelayCreateRequest( []string{"ASSET_REPORT_TOKEN"}, clientIdFromPartner ), ).Execute() ``` #### Response fields  string A token that can be shared with a third party to allow them to access the Asset Report. This token should be stored securely. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "relay_token": "credit-relay-production-3TAU2CWVYBDVRHUCAAAI27ULU4", "request_id": "Iam3b" } ``` \=\*=\*=\*= #### /credit/relay/get  #### Retrieve the reports associated with a relay token that was shared with you  [/credit/relay/get](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayget) allows third parties to receive a report that was shared with them, using a `relay_token` that was created by the report owner. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The `relay_token` granting access to the report you would like to get. required, string The report type. It can be `asset`. Income report types are not yet supported. Possible values: `asset` boolean `true` if you would like to retrieve the Asset Report with Insights, `false` otherwise. This field defaults to `false` if omitted. Default: `false` ```python request = CreditRelayGetRequest( relay_token=relay_token, report_type='assets' ) response = client.credit_relay_get(request) ``` ```bash curl -X POST https://sandbox.plaid.com/credit/relay/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "relay_token": String, "report_type": String, }' ``` ```java CreditRelayGetRequest request = new CreditRelayGetRequest() .relayToken(relayToken) .reportType("assets"); Response response = client().creditRelayGet(request).execute(); ``` ```ruby request = Plaid::CreditRelayGetRequest.new( { relay_token: relay_token, report_type: 'assets' } ) response = client.credit_relay_get(request) ``` ```node const request: CreditRelayGetRequest = { relay_token: createResponse.data.relay_token, report_type: 'assets', }; try { const response = await plaidClient.creditRelayGet(request); } catch (error) { // handle error } ``` ```go response, _, err := client.PlaidApi.CreditRelayGet(ctx).CreditRelayGetRequest( *plaid.NewCreditRelayGetRequest( "relay_token", "assets", ), ).Execute() ``` #### Response fields  object An object representing an Asset Report string A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. nullable, object This is a container object for all lending-related insights. This field will be returned only for European customers. nullable, object Risk indicators focus on providing signal on the possibility of a borrower defaulting on their loan repayments by providing data points related to its payment behavior, debt, and other relevant financial information, helping lenders gauge the level of risk involved in a certain operation. nullable, object Insights into bank penalties and fees, including overdraft fees, NSF fees, and other bank-imposed charges. nullable, number The total value of outflow transactions categorized as `BANK_PENALTIES`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of transactions that fall into the `BANK_PENALTIES` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `BANK_PENALTIES` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into the `BANK_PENALTIES` credit category. If there's no available income for the given time period, this field value will be `-1`. Format: `double` nullable, object Insights into gambling-related transactions, including frequency, amounts, and top merchants. nullable, number The total value of transactions that fall into the `GAMBLING` credit category, across all the accounts in the report. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top merchants that the user had the most transactions for in the given time window, in descending order of total spend. If the user has not spent money on any merchants in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `GAMBLING` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `GAMBLING` category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `GAMBLING` category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `GAMBLING` category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `GAMBLING` credit category. If there's no available income for the given time period, this field value will be `-1` Format: `double` nullable, object Insights into loan disbursement transactions received by the user, tracking incoming funds from loan providers. nullable, number The total value of inflow transactions categorized as `LOAN_DISBURSEMENTS`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `LOAN_DISBURSEMENTS` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top service providers that the user had the most transactions for in the given time window, in descending order of total spend. If the user has received money from any provider in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `LOAN_DISBURSEMENTS` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `LOAN_DISBURSEMENTS` category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `LOAN_DISBURSEMENTS` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was received on transactions that fall into the `LOAN_DISBURSEMENTS` credit category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `LOAN_DISBURSEMENTS` credit category. If there's no available income for the given time period, this field value will be `-1`. Format: `double` nullable, object Insights into loan payment transactions made by the user, tracking outgoing payments to loan providers. nullable, number The total value of outflow transactions categorized as `LOAN_PAYMENTS`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top service providers that the user had the most transactions for in the given time window, in descending order of total spend. If the user has not spent money on any provider in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `LOAN_PAYMENTS` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `LOAN_PAYMENTS` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `LOAN_PAYMENTS` credit category. If there's no available income for the giving time period, this field value will be `-1` Format: `double` nullable, object Insights into negative balance occurrences, including frequency, duration, and minimum balance details. nullable, integer The number of days since the last transaction that caused any account in the report to have a negative balance. This value is inclusive of the date of the last negative balance, meaning that if the last negative balance occurred today, this value will be `0`. nullable, integer The number of aggregated days that the accounts in the report has had a negative balance within the given time window. nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] The summary of the negative balance occurrences for this account. If the user has not had a negative balance in the account in the given time window, this list will be empty. nullable, string The date of the first transaction that caused the account to have a negative balance. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` nullable, string The date of the last transaction that caused the account to have a negative balance. The date will be returned in an ISO 8601 format (YYYY-MM-DD). This date is inclusive, meaning that this was the last date that the account had a negative balance. Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Affordability insights focus on providing signal on the ability of a borrower to repay their loan without experiencing financial strain. It provides insights on factors such a user's monthly income and expenses, disposable income, average expenditure, etc., helping lenders gauge the level of affordability of a borrower. nullable, object Comprehensive analysis of spending patterns, categorizing expenses into essential, non-essential, and other categories. nullable, object Net cash flow for the period (inflows minus outflows), including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Insights into unusually large transactions that exceed typical spending patterns for the account. nullable, integer The total number of transactions whose value is above the threshold of normal amounts for a given account. nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Up to 3 top categories of expenses in this group. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Comprehensive income analysis including total income, income excluding transfers, and inbound transfer amounts. nullable, object The total amount of all income transactions in the given time period. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Income excluding account transfer transactions for the period, including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Sum of inbound transfer transactions for the period, including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string An identifier you determine and submit for the Asset Report. string The date and time when the Asset Report was created, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (e.g. "2018-04-12T03:32:11Z"). Format: `date-time` number The duration of transaction history you requested object The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The `first_name`, `last_name`, and `ssn` fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program. nullable, string An identifier you determine and submit for the user. nullable, string The user's first name. Required for the Fannie Mae Day 1 Certainty™ program. nullable, string The user's middle name nullable, string The user's last name. Required for the Fannie Mae Day 1 Certainty™ program. nullable, string The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program. Format: "ddd-dd-dddd" nullable, string The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis. nullable, string The user's email address. \[object\] Data returned by Plaid about each of the Items included in the Asset Report. string The `item_id` of the Item associated with this webhook, warning, or error string The full financial institution name associated with the Item. string The id of the financial institution associated with the Item. string The date and time when this Item’s data was last retrieved from the financial institution, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` \[object\] Data about each of the accounts open on the Item. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get`. nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get`; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, number The total amount of borrowed funds in the account, as determined by the financial institution. For investment-type accounts, the margin balance is the total value of borrowed assets in the account, as presented by the institution. This is commonly referred to as margin or a loan. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the oldest acceptable balance when making a request to `/accounts/balance/get`. This field is only used and expected when the institution is `ins_128026` (Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an `INVALID_REQUEST` error with the code of `INVALID_FIELD` will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See [account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of account types. If the balance that is pulled is older than the given timestamp for Items with this field required, an `INVALID_REQUEST` error with the code of `LAST_UPDATED_DATETIME_OUT_OF_RANGE` will be returned with the most recent timestamp for the requested account contained in the response. Format: `date-time` nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only. `pending_automatic_verification`: The Item is pending automatic verification `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the micro-deposit. `automatically_verified`: The Item has successfully been automatically verified `manually_verified`: The Item has successfully been manually verified `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `database_matched`: The Item has successfully been verified using Plaid's data sources. Note: Database Match is currently a beta feature, please contact your account manager for more information. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items. number The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account. \[object\] Transaction history associated with the account. string The ID of the account in which this transaction occurred. number The settled value of the transaction, denominated in the transaction's currency, as stated in `iso_currency_code` or `unofficial_currency_code`. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. Format: `double` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string The string returned by the financial institution to describe the transaction. nullable, \[string\] A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) . This field will only appear in an Asset Report with Insights. nullable, string The ID of the category to which this transaction belongs. For a full list of categories, see [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) . This field will only appear in an Asset Report with Insights. nullable, object Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. See the [taxonomy csv file](https://plaid.com/documents/credit-category-taxonomy.csv) for a full list of credit categories. string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string The check number of the transaction. This field is only populated for check transactions. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). Format: `date` nullable, string The date on which the transaction took place, in IS0 8601 format. object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. deprecated, string The merchant name or transaction description. This is a legacy field that is no longer maintained. For merchant name, use the `merchant_name` field. For description, use the `original_description` field. This field will only appear in an Asset Report with Insights. nullable, string The merchant name, as enriched by Plaid. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be `null`. object Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be `null`. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, the `payment_meta` key will always appear, but no data elements are guaranteed. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The transaction reference number supplied by the financial institution. nullable, string The ACH PPD ID for the payer. nullable, string For transfers, the party that is receiving the transaction. nullable, string The party initiating a wire transfer. Will be `null` if the transaction is not a wire transfer. nullable, string For transfers, the party that is paying the transaction. nullable, string The type of transfer, e.g. 'ACH' nullable, string The name of the payment processor nullable, string The payer-supplied description of the transfer. boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. nullable, string The ID of a posted transaction's associated pending transaction, where applicable. nullable, string The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. string `digital:` transactions that took place online. `place:` transactions that were made at a physical location. `special:` transactions that relate to banks, e.g. fees or deposits. `unresolved:` transactions that do not fit into the other three types. Possible values: `digital`, `place`, `special`, `unresolved` object A set of fields describing the investments data on an account. \[object\] Quantities and values of securities held in the investment account. Map to the `securities` array for security details. string The Plaid `account_id` associated with the holding. string The Plaid `security_id` associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The `security_id` for the same security will typically be the same across different institutions, but this is not guaranteed. The `security_id` does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. nullable, string The holding's trading symbol for publicly traded holdings, and otherwise a short identifier if available. number The last price given by the institution for this security. Format: `double` nullable, string The date at which `institution_price` was current. Format: `date` number The value of the holding, as reported by the institution. Format: `double` nullable, number The original total value of the holding. This field is calculated by Plaid as the sum of the purchase price of all of the shares in the holding. Format: `double` number The total quantity of the asset held, as reported by the financial institution. If the security is an option, `quantity` will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts. Format: `double` nullable, string The ISO-4217 currency code of the holding. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the holding. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. \[object\] Details of specific securities held in on the investment account. string A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the `security_id` is case sensitive. The `security_id` may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. nullable, string A descriptive name for the security, suitable for display. nullable, string The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available. nullable, string The security type of the holding. Valid security types are: `cash`: Cash, currency, and money market funds `cryptocurrency`: Digital or virtual currencies `derivative`: Options, warrants, and other derivative instruments `equity`: Domestic and foreign equities `etf`: Multi-asset exchange-traded investment funds `fixed income`: Bonds and certificates of deposit (CDs) `loan`: Loans and loan receivables `mutual fund`: Open- and closed-end vehicles pooling funds of multiple investors `other`: Unknown or other investment types \[object\] Transaction history on the investment account. string The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the `investment_transaction_id` is case sensitive. string The `account_id` of the account against which this transaction posted. nullable, string The `security_id` to which this transaction is related. string The [ISO 8601](https://wikipedia.org/wiki/ISO_8601) posting date for the transaction. Format: `date` string The institution’s description of the transaction. number The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions. Format: `double` number The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with [equities](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-type) . Format: `double` number The value of the vested holdings as reported by the institution. Format: `double` number The complete value of the transaction. Positive values when cash is debited, e.g. purchases of stock; negative values when cash is credited, e.g. sales of stock. Treatment remains the same for cash-only movements unassociated with securities. Format: `double` number The price of the security at which this transaction occurred. Format: `double` nullable, number The combined value of all fees applied to this transaction Format: `double` string Value is one of the following: `buy`: Buying an investment `sell`: Selling an investment `cancel`: A cancellation of a pending transaction `cash`: Activity that modifies a cash position `fee`: A fee on the account `transfer`: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer For descriptions of possible transaction types and subtypes, see the [Investment transaction types schema](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Possible values: `buy`, `sell`, `cancel`, `cash`, `fee`, `transfer` string For descriptions of possible transaction types and subtypes, see the [Investment transaction types schema](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Possible values: `account fee`, `adjustment`, `assignment`, `buy`, `buy to cover`, `contribution`, `deposit`, `distribution`, `dividend`, `dividend reinvestment`, `exercise`, `expire`, `fund fee`, `interest`, `interest receivable`, `interest reinvestment`, `legal fee`, `loan payment`, `long-term capital gain`, `long-term capital gain reinvestment`, `management fee`, `margin expense`, `merger`, `miscellaneous fee`, `non-qualified dividend`, `non-resident tax`, `pending credit`, `pending debit`, `qualified dividend`, `rebalance`, `return of principal`, `request`, `sell`, `sell short`, `send`, `short-term capital gain`, `short-term capital gain reinvestment`, `spin off`, `split`, `stock distribution`, `tax`, `tax withheld`, `trade`, `transfer`, `transfer fee`, `trust fee`, `unqualified gain`, `withdrawal` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the holding. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. \[object\] Data returned by the financial institution about the account owner or owners.For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same `owner` object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the `owners` object is not returned, and instead identity information is returned in the top level `identity` object. For more details, see [Plaid API versioning](https://plaid.com/docs/api/versioning/index.html.md#version-2019-05-29) \[string\] A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's `names` array. \[object\] A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The phone number. boolean When `true`, identifies the phone number as the primary number on an account. string The type of phone number. Possible values: `home`, `work`, `office`, `mobile`, `mobile1`, `other` \[object\] A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The email address. boolean When `true`, identifies the email address as the primary email on an account. string The type of email account as described by the financial institution. Possible values: `primary`, `secondary`, `other` \[object\] Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. object Data about the components comprising an address. nullable, string The full city name nullable, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code boolean When `true`, identifies the address as the primary address on an account. nullable, string How an asset is owned. `association`: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. `individual`: Ownership by an individual. `joint`: Joint ownership by multiple parties. `trust`: Ownership by a revocable or irrevocable trust. Possible values: `null`, `individual`, `joint`, `association`, `trust` \[object\] Calculated data about the historical balances on the account. Available for `credit` and `depository` type accounts. string The date of the calculated historical balance, in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD) Format: `date` number The total amount of funds in the account, calculated from the `current` balance in the `balance` object by subtracting inflows and adding back outflows according to the posted date of each transaction. If the account has any pending transactions, historical balance amounts on or after the date of the earliest pending transaction may differ if retrieved in subsequent Asset Reports as a result of those pending transactions posting. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the balance. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object This is a container object for all lending-related insights. This field will be returned only for European customers. nullable, object Risk indicators focus on providing signal on the possibility of a borrower defaulting on their loan repayments by providing data points related to its payment behavior, debt, and other relevant financial information, helping lenders gauge the level of risk involved in a certain operation. nullable, object Insights into bank penalties and fees, including overdraft fees, NSF fees, and other bank-imposed charges. nullable, number The total value of outflow transactions categorized as `BANK_PENALTIES`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of transactions that fall into the `BANK_PENALTIES` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `BANK_PENALTIES` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `BANK_PENALTIES` credit category within the given time window, across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into the `BANK_PENALTIES` credit category. If there's no available income for the given time period, this field value will be `-1`. Format: `double` nullable, object Insights into gambling-related transactions, including frequency, amounts, and top merchants. nullable, number The total value of transactions that fall into the `GAMBLING` credit category, across all the accounts in the report. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top merchants that the user had the most transactions for in the given time window, in descending order of total spend. If the user has not spent money on any merchants in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `GAMBLING` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `GAMBLING` category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `GAMBLING` category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `GAMBLING` category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `GAMBLING` credit category. If there's no available income for the given time period, this field value will be `-1` Format: `double` nullable, object Insights into loan disbursement transactions received by the user, tracking incoming funds from loan providers. nullable, number The total value of inflow transactions categorized as `LOAN_DISBURSEMENTS`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `LOAN_DISBURSEMENTS` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top service providers that the user had the most transactions for in the given time window, in descending order of total spend. If the user has received money from any provider in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `LOAN_DISBURSEMENTS` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `LOAN_DISBURSEMENTS` category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `LOAN_DISBURSEMENTS` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was received on transactions that fall into the `LOAN_DISBURSEMENTS` credit category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `LOAN_DISBURSEMENTS` credit category. If there's no available income for the given time period, this field value will be `-1`. Format: `double` nullable, object Insights into loan payment transactions made by the user, tracking outgoing payments to loan providers. nullable, number The total value of outflow transactions categorized as `LOAN_PAYMENTS`, across all the accounts in the report within the requested time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Detailed categories view of all the transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[string\] Up to 3 top service providers that the user had the most transactions for in the given time window, in descending order of total spend. If the user has not spent money on any provider in the given time window, this list will be empty. nullable, integer The total number of transactions that fall into the `LOAN_PAYMENTS` credit category, across all the accounts in the report. \[object\] The monthly summaries of the transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. nullable, string The start date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The end date of the month for the given report time window. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The number of days since the last transaction that falls into the `LOAN_PAYMENTS` credit category, across all the accounts in the report. nullable, number The percentage of the user's monthly inflows that was spent on transactions that fall into the `LOAN_PAYMENTS` credit category within the given time window, across all the accounts in the report. For example, a value of 100 indicates that 100% of the inflows were spent on transactions that fall into the `LOAN_PAYMENTS` credit category. If there's no available income for the giving time period, this field value will be `-1` Format: `double` nullable, object Insights into negative balance occurrences, including frequency, duration, and minimum balance details. nullable, integer The number of days since the last transaction that caused any account in the report to have a negative balance. This value is inclusive of the date of the last negative balance, meaning that if the last negative balance occurred today, this value will be `0`. nullable, integer The number of aggregated days that the accounts in the report has had a negative balance within the given time window. nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] The summary of the negative balance occurrences for this account. If the user has not had a negative balance in the account in the given time window, this list will be empty. nullable, string The date of the first transaction that caused the account to have a negative balance. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` nullable, string The date of the last transaction that caused the account to have a negative balance. The date will be returned in an ISO 8601 format (YYYY-MM-DD). This date is inclusive, meaning that this was the last date that the account had a negative balance. Format: `date` nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Affordability insights focus on providing signal on the ability of a borrower to repay their loan without experiencing financial strain. It provides insights on factors such a user's monthly income and expenses, disposable income, average expenditure, etc., helping lenders gauge the level of affordability of a borrower. nullable, object Comprehensive analysis of spending patterns, categorizing expenses into essential, non-essential, and other categories. nullable, object Net cash flow for the period (inflows minus outflows), including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Summary statistics for a specific expenditure category, including total amount, monthly average, and percentage of income. nullable, number The total value of all the aggregated transactions in this expenditure category. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, integer The total number of outflow transactions in this expenses group, within the given time window across all the accounts in the report. nullable, number The percentage of the total inflows that was spent in this expenses group, within the given time window across all the accounts in the report. For example, a value of 100 represents that 100% of the inflows were spent on transactions that fall into this expenditure group. If there's no available income for the giving time period, this field value will be `-1`. Format: `double` \[object\] The primary credit categories of the expenses within the given time window, across all the accounts in the report. The categories are sorted in descending order by the total value spent. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Insights into unusually large transactions that exceed typical spending patterns for the account. nullable, integer The total number of transactions whose value is above the threshold of normal amounts for a given account. nullable, object A monetary amount with its associated currency information, supporting both official and unofficial currency codes. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Up to 3 top categories of expenses in this group. string The ID of the credit category. See the [category taxonomy](https://plaid.com/documents/credit-category-taxonomy.csv) for a full listing of category IDs. nullable, integer The total number of transactions that fall into this credit category within the given time window. nullable, number The total value for all the transactions that fall into this category within the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object The monthly average amount calculated by dividing the total by the number of calendar months in the time period. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Comprehensive income analysis including total income, income excluding transfers, and inbound transfer amounts. nullable, object The total amount of all income transactions in the given time period. nullable, number If the parent object represents a category of transactions, such as `total_amount`, `transfers_in`, `total_income`, etc. the `amount` represents the sum of all of the transactions in the group. If the parent object is `cash_flow`, the `amount` represents the total value of all the inflows minus all the outflows across all the accounts in the report in the given time window. If the parent object is `minimum_balance`, the `amount` represents the lowest balance of the account during the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Income excluding account transfer transactions for the period, including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, object Sum of inbound transfer transactions for the period, including a monthly average. nullable, number The monthly average amount of all the aggregated transactions of the given category, across all the accounts for the given time window. The average is calculated by dividing the total amount of the transactions by the number of calendar months in the given time window. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the amount. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] If the Asset Report generation was successful but identity information cannot be returned, this array will contain information about the errors causing identity information to be missing string The warning type, which will always be `ASSET_REPORT_WARNING` string The warning code identifies a specific kind of warning. `OWNERS_UNAVAILABLE` indicates that account-owner information is not available.`INVESTMENTS_UNAVAILABLE` indicates that Investments specific information is not available. `TRANSACTIONS_UNAVAILABLE` indicates that transactions information associated with Credit and Depository accounts are unavailable. Possible values: `OWNERS_UNAVAILABLE`, `INVESTMENTS_UNAVAILABLE`, `TRANSACTIONS_UNAVAILABLE` nullable, object An error object and associated `item_id` used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The `item_id` of the Item associated with this webhook, warning, or error string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "report": { "asset_report_id": "028e8404-a013-4a45-ac9e-002482f9cafc", "client_report_id": "client_report_id_1221", "date_generated": "2023-03-30T18:27:37Z", "days_requested": 90, "items": [ { "accounts": [ { "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8", "balances": { "available": 43200, "current": 43200, "limit": null, "margin_loan_amount": null, "iso_currency_code": "USD", "unofficial_currency_code": null }, "days_available": 90, "historical_balances": [ { "current": 49050, "date": "2023-03-29", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 49050, "date": "2023-03-28", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 49050, "date": "2023-03-27", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 49050, "date": "2023-03-26", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 49050, "date": "2023-03-25", "iso_currency_code": "USD", "unofficial_currency_code": null } ], "mask": "4444", "name": "Plaid Money Market", "official_name": "Plaid Platinum Standard 1.85% Interest Money Market", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "region": "NY", "street": "2992 Cameron Road", "postal_code": "14236" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "region": "CA", "street": "2493 Leisure Lane", "postal_code": "93405-2255" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholder1@example.com", "primary": false, "type": "secondary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "+1 111-555-3333", "primary": false, "type": "home" }, { "data": "+1 111-555-4444", "primary": false, "type": "work" }, { "data": "+1 111-555-5555", "primary": false, "type": "mobile" } ] } ], "ownership_type": null, "subtype": "money market", "transactions": [ { "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8", "amount": 5850, "date": "2023-03-30", "iso_currency_code": "USD", "original_description": "ACH Electronic CreditGUSTO PAY 123456", "pending": false, "transaction_id": "gGQgjoeyqBF89PND6K14Sow1wddZBmtLomJ78", "unofficial_currency_code": null } ], "type": "depository" }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "balances": { "available": 100, "current": 110, "limit": null, "margin_loan_amount": null, "iso_currency_code": "USD", "unofficial_currency_code": null }, "days_available": 90, "historical_balances": [ { "current": 110, "date": "2023-03-29", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": -390, "date": "2023-03-28", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": -373.67, "date": "2023-03-27", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": -284.27, "date": "2023-03-26", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": -284.27, "date": "2023-03-25", "iso_currency_code": "USD", "unofficial_currency_code": null } ], "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "region": "NY", "street": "2992 Cameron Road", "postal_code": "14236" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "region": "CA", "street": "2493 Leisure Lane", "postal_code": "93405-2255" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholder1@example.com", "primary": false, "type": "secondary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "+1 111-555-3333", "primary": false, "type": "home" }, { "data": "+1 111-555-4444", "primary": false, "type": "work" }, { "data": "+1 111-555-5555", "primary": false, "type": "mobile" } ] } ], "ownership_type": null, "subtype": "checking", "transactions": [ { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": 89.4, "date": "2023-03-27", "iso_currency_code": "USD", "original_description": "SparkFun", "pending": false, "transaction_id": "4zBRq1Qem4uAPnoyKjJNTRQpQddM4ztlo1PLD", "unofficial_currency_code": null }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": 12, "date": "2023-03-28", "iso_currency_code": "USD", "original_description": "McDonalds #3322", "pending": false, "transaction_id": "dkjL41PnbKsPral79jpxhMWdW55gkPfBkWpRL", "unofficial_currency_code": null }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": 4.33, "date": "2023-03-28", "iso_currency_code": "USD", "original_description": "Starbucks", "pending": false, "transaction_id": "a84ZxQaWDAtDL3dRgmazT57K7jjN3WFkNWMDy", "unofficial_currency_code": null }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": -500, "date": "2023-03-29", "iso_currency_code": "USD", "original_description": "United Airlines **** REFUND ****", "pending": false, "transaction_id": "xG9jbv3eMoFWepzB7wQLT3LoLggX5Duy1Gbe5", "unofficial_currency_code": null } ], "type": "depository" } ], "date_last_updated": "2023-03-30T18:25:26Z", "institution_id": "ins_109508", "institution_name": "First Platypus Bank", "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7" } ], "user": { "client_user_id": "uid_40332", "email": "abcharleston@example.com", "first_name": "Anna", "last_name": "Charleston", "middle_name": "B", "phone_number": "1-415-867-5309", "ssn": "111-22-1234" } }, "request_id": "GVzMdiDd8DDAQK4", "warnings": [] } ``` \=\*=\*=\*= #### /credit/relay/refresh  #### Refresh a report of a relay token  The [/credit/relay/refresh](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayrefresh) endpoint allows third parties to refresh a report that was relayed to them, using a `relay_token` that was created by the report owner. A new report will be created with the original report parameters, but with the most recent data available based on the `days_requested` value of the original report. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The `relay_token` granting access to the report you would like to refresh. required, string The report type. It can be `asset`. Income report types are not yet supported. Possible values: `asset` string The URL registered to receive webhooks when the report of a relay token has been refreshed. Format: `url` ```python request = CreditRelayRefreshRequest( relay_token=relay_token, report_type='assets' ) response = client.credit_relay_refresh(request) ``` ```bash curl -X POST https://sandbox.plaid.com/credit/relay/refresh \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "relay_token": String, "report_type": String, }' ``` ```java CreditRelayRefreshRequest request = new CreditRelayRefreshRequest() .relayToken(relayToken) .reportType("assets"); Response response = client().creditRelayRefresh(request).execute(); ``` ```ruby request = Plaid::CreditRelayRefreshRequest.new( { relay_token: relay_token, report_type: 'assets' } ) response = client.credit_relay_refresh(request) ``` ```node const request: CreditRelayRefreshRequest = { relay_token: createResponse.data.relay_token, report_type: 'assets', }; try { const response = await plaidClient.creditRelayRefresh(request); } catch (error) { // handle error } ``` ```go response, _, err := client.PlaidApi.CreditRelayRefresh(ctx).CreditRelayRefreshRequest( *plaid.NewCreditRelayRefreshRequest( "relay_token", "assets", ), ).Execute() ``` #### Response fields  string string A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "relay_token": "credit-relay-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398", "request_id": "NBZaq", "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d" } ``` \=\*=\*=\*= #### /credit/relay/remove  #### Remove relay token  The [/credit/relay/remove](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayremove) endpoint allows you to invalidate a `relay_token`. The third party holding the token will no longer be able to access or refresh the reports which the `relay_token` gives access to. The original report, associated Items, and other relay tokens that provide access to the same report are not affected and will remain accessible after removing the given `relay_token`. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The `relay_token` you would like to revoke. ```python request = CreditRelayRemoveRequest( relay_token=relay_token ) response = client.credit_relay_remove(request) ``` ```bash curl -X POST https://sandbox.plaid.com/credit/relay/remove \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "relay_token": String, }' ``` ```java CreditRelayRemoveRequest request = new CreditRelayRemoveRequest() .relayToken(relayToken); Response response = client().creditRelayRemove(request).execute(); ``` ```ruby request = Plaid::CreditRelayRemoveRequest.new( { relay_token: relay_token } ) response = client.credit_relay_remove(request) ``` ```node const request: CreditRelayRemoveRequest = { relay_token: createResponse.data.relay_token, }; try { const response = await plaidClient.creditRelayRemove(request); } catch (error) { // handle error } ``` ```go response, _, err := client.PlaidApi.CreditRelayRemove(ctx).CreditRelayRemoveRequest( *plaid.NewCreditRelayRemoveRequest( "relay_token", ), ).Execute() ``` #### Response fields  boolean `true` if the relay token was successfully removed. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "removed": true, "request_id": "m8MDnv9okwxFNBV" } ``` ### Webhooks  \=\*=\*=\*= #### PRODUCT\_READY  Fired when the Asset Report has been generated and [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) is ready to be called. If you attempt to retrieve an Asset Report before this webhook has fired, you’ll receive a response with the HTTP status code 400 and a Plaid error code of `PRODUCT_NOT_READY`. #### Properties  string `ASSETS` string `PRODUCT_READY` string The `asset_report_id` corresponding to the Asset Report the webhook has fired for. string The `user_id` corresponding to the User ID the webhook has fired for. string Indicates either a Fast Asset Report, which will contain only current identity and balance information, or a Full Asset Report, which will also contain historical balance information and transaction data. Possible values: `FULL`, `FAST` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "ASSETS", "webhook_code": "PRODUCT_READY", "asset_report_id": "47dfc92b-bba3-4583-809e-ce871b321f05", "report_type": "FULL" } ``` \=\*=\*=\*= #### ERROR  Fired when Asset Report generation has failed. The resulting `error` will have an `error_type` of `ASSET_REPORT_ERROR`. #### Properties  string `ASSETS` string `ERROR` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The ID associated with the Asset Report. string The `user_id` corresponding to the User ID the webhook has fired for. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "ASSETS", "webhook_code": "ERROR", "asset_report_id": "47dfc92b-bba3-4583-809e-ce871b321f05", "error": { "display_message": null, "error_code": "PRODUCT_NOT_ENABLED", "error_message": "the 'assets' product is not enabled for the following access tokens: access-sandbox-fb88b20c-7b74-4197-8d01-0ab122dad0bc. please ensure that 'assets' is included in the 'product' array when initializing Link and create the Item(s) again.", "error_type": "ASSET_REPORT_ERROR", "request_id": "m8MDnv9okwxFNBV" } } ``` --- # API - Auth | Plaid Docs Auth  ===== #### API reference for Auth endpoints and webhooks  Retrieve bank account information to set up electronic funds transfers, such as ACH payments in the US, EFT payments in Canada, BACS payments in the UK, and IBAN / SIC payments in the EU. For how-to guidance, see the [Auth documentation](https://plaid.com/docs/auth/index.html.md) . | Endpoints | | | --- | --- | | [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) | Get bank account and routing number and verification status | | [/auth/verify](https://plaid.com/docs/api/products/auth/index.html.md#authverify) | Verify a user's bank account information using [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) | | [/bank\_transfer/event/list](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventlist) | Search for updates on micro-deposit verification statuses based on filter criteria | | [/bank\_transfer/event/sync](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventsync) | Get updates on micro-deposit verification statuses using a cursor | | See also | | | --- | --- | | [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) | Create a token for using Auth with a processing partner | | [/sandbox/processor\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxprocessor_tokencreate) | Create a token for testing Auth with a processing partner | | [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) | Create a token for using Auth with Stripe as a processing partner | | [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) | Change a Sandbox Item's micro-deposit verification status | | Webhooks | | | --- | --- | | [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/auth/index.html.md#default_update) | Item has account(s) with updated Auth data | | [AUTOMATICALLY\_VERIFIED](https://plaid.com/docs/api/products/auth/index.html.md#automatically_verified) | Item has been verified | | [VERIFICATION\_EXPIRED](https://plaid.com/docs/api/products/auth/index.html.md#verification_expired) | Item verification has failed | | [BANK\_TRANSFERS\_EVENTS\_UPDATE](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfers_events_update) | New micro-deposit verification events available | | [SMS\_MICRODEPOSITS\_VERIFICATION](https://plaid.com/docs/api/products/auth/index.html.md#sms_microdeposits_verification) | Text message verification status has changed | ### Endpoints  \=\*=\*=\*= #### /auth/get  #### Retrieve auth data  The [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) endpoint returns the bank account and bank identification numbers (such as routing numbers, for US accounts) associated with an Item's checking, savings, and cash management accounts, along with high-level account data and balances when available. Versioning note: In API version 2017-03-08, the schema of the `numbers` object returned by this endpoint is substantially different. For details, see [Plaid API versioning](https://plaid.com/docs/api/versioning/index.html.md#version-2018-05-22) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. object An optional object to filter `/auth/get` results. \[string\] A list of `account_ids` to retrieve for the Item. Note: An error will be returned if a provided `account_id` is not associated with the Item. ```node const request: AuthGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.authGet(request); const accountData = response.data.accounts; const numbers = response.data.numbers; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/auth/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "options": { "account_ids": [String] } }' ``` ```ruby request = Plaid::AuthGetRequest.new({ access_token: access_token }) response = client.auth_get(request) numbers = response.numbers ``` ```java AuthGetRequest authGetRequest = new AuthGetRequest() .accessToken(accessToken); Response response = client() .authGet(authGetRequest) .execute(); AuthGetResponse.Numbers numbers = response.body().getNumbers(); ``` ```python request = AuthGetRequest(access_token=access_token) response = client.auth_get(request) numbers = response['numbers'] ``` ```go authGetResp, _, err := client.PlaidApi.AuthGet(ctx).AuthGetRequest( *plaid.NewAuthGetRequest(accessToken), ).Execute() numbers := authGetResp.GetNumbers() ``` #### Response fields  \[object\] The `accounts` for which numbers are being retrieved. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` object An object containing identifying numbers used for making electronic transfers to and from the `accounts`. The identifying number type (ACH, EFT, IBAN, or BACS) used will depend on the country of the account. An account may have more than one number type. If a particular identifying number type is not used by any `accounts` for which data has been requested, the array for that type will be empty. \[object\] An array of ACH numbers identifying accounts. string The Plaid account ID associated with the account numbers string The ACH account number for the account. At certain institutions, including Chase, PNC, and (coming May 2025) US Bank, you will receive "tokenized" routing and account numbers, which are not the user's actual account and routing numbers. For important details on how this may impact your integration and on how to avoid fraud, user confusion, and ACH returns, see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) . boolean Indicates whether the account number is tokenized by the institution. For important details on how tokenized account numbers may impact your integration, see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) . string The ACH routing number for the account. This may be a tokenized routing number. For more information, see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) . nullable, string The wire transfer routing number for the account. This field is only populated if the institution is known to use a separate wire transfer routing number. Many institutions do not have a separate wire routing number and use the ACH routing number for wires instead. It is recommended to have the end user manually confirm their wire routing number before sending any wires to their account, especially if this field is `null`. \[object\] An array of EFT numbers identifying accounts. string The Plaid account ID associated with the account numbers string The EFT account number for the account string The EFT institution number for the account string The EFT branch number for the account \[object\] An array of IBAN numbers identifying accounts. string The Plaid account ID associated with the account numbers string The International Bank Account Number (IBAN) for the account string The Bank Identifier Code (BIC) for the account \[object\] An array of BACS numbers identifying accounts. string The Plaid account ID associated with the account numbers string The BACS account number for the account string The BACS sort code for the account object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "accounts": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "balances": { "available": 100, "current": 110, "limit": null, "iso_currency_code": "USD", "unofficial_currency_code": null }, "mask": "9606", "name": "Plaid Checking", "official_name": "Plaid Gold Checking", "subtype": "checking", "type": "depository" } ], "numbers": { "ach": [ { "account": "9900009606", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "routing": "011401533", "wire_routing": "021000021", "is_tokenized_account_number": false } ], "eft": [ { "account": "111122223333", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "institution": "021", "branch": "01140" } ], "international": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "bic": "NWBKGB21", "iban": "GB29NWBK60161331926819" } ], "bacs": [ { "account": "31926819", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "sort_code": "601613" } ] }, "item": { "available_products": [ "balance", "identity", "payment_initiation", "transactions" ], "billed_products": [ "assets", "auth" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_117650", "institution_name": "Royal Bank of Plaid", "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6", "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook", "auth_method": "INSTANT_AUTH" }, "request_id": "m8MDnv9okwxFNBV" } ``` \=\*=\*=\*= #### /auth/verify  #### Verify auth data  The [/auth/verify](https://plaid.com/docs/api/products/auth/index.html.md#authverify) endpoint verifies bank account and routing numbers and (optionally) account owner names against Plaid's database via [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) . It can be used to verify account numbers that were not collected via the Plaid Link flow. This endpoint is currently in Early Availability; contact Sales or your Plaid account manager to request access. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Account owner's legal name required, object An object containing identifying account numbers for verification via Database Auth required, object ACH numbers for verification via Database Auth required, string Account's account number required, string Account's routing number ```node const request: AuthVerifyRequest = { numbers: { ach: { account: '1234567890', routing: '011401533', }, }, legal_name: 'Jane Doe', }; try { const response = await plaidClient.authVerify(request); const verificationStatus = response.data.verification_status; const nameMatchScore = response.data.verification_insights.name_match_score; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/auth/verify \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "numbers": { "ach": { "account": "1234567890", "routing": "011401533" } }, "legal_name": "Jane Doe" }' ``` ```ruby request = Plaid::AuthVerifyRequest.new({ numbers: { ach: { account: '1234567890', routing: '011401533', }, }, legal_name: 'Jane Doe', }) response = client.auth_verify(request) verification_status = response.verification_status name_match_score = response.verification_insights.name_match_score ``` ```java AuthVerifyRequestNumbers numbers = new AuthVerifyRequestNumbers() .ach(new AuthVerifyNumbersACH() .account("1234567890") .routing("011401533")); AuthVerifyRequest authVerifyRequest = new AuthVerifyRequest() .numbers(numbers) .legalName("Jane Doe"); Response response = client() .authVerify(authVerifyRequest) .execute(); String verificationStatus = response.body().getVerificationStatus(); Integer nameMatchScore = response.body().getVerificationInsights().getNameMatchScore(); ``` ```python request = AuthVerifyRequest( numbers=AuthVerifyRequestNumbers( ach=AuthVerifyNumbersACH( account='1234567890', routing='011401533', ), ), legal_name='Jane Doe', ) response = client.auth_verify(request) verification_status = response['verification_status'] name_match_score = response['verification_insights']['name_match_score'] ``` ```go numbers := *plaid.NewAuthVerifyRequestNumbers( *plaid.NewAuthVerifyNumbersACH("1234567890", "011401533"), ) request := *plaid.NewAuthVerifyRequest(numbers) request.SetLegalName("Jane Doe") authVerifyResp, _, err := client.PlaidApi.AuthVerify(ctx).AuthVerifyRequest( request, ).Execute() verificationStatus := authVerifyResp.GetVerificationStatus() nameMatchScore := authVerifyResp.GetVerificationInsights().GetNameMatchScore() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. nullable, string The `item_id` value of the Item created for verification. If numbers data provided is invalid, an item may not be created. string Indicates the Item's database verification status. Possible values are: `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` Response Object ```json { "request_id": "m8MDnv9okwxFNBV", "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6", "verification_status": "database_insights_pass", "verification_insights": { "name_match_score": 85, "network_status": { "has_numbers_match": true, "is_numbers_match_verified": true }, "previous_returns": { "has_previous_administrative_return": false }, "account_number_format": "valid" } } ``` \=\*=\*=\*= #### /bank\_transfer/event/list  #### List bank transfer events  Use the [/bank\_transfer/event/list](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventlist) endpoint to get a list of Plaid-initiated ACH or bank transfer events based on specified filter criteria. When using Auth with micro-deposit verification enabled, this endpoint can be used to fetch status updates on ACH micro-deposits. For more details, see [micro-deposit events](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The start datetime of bank transfers to list. This should be in RFC 3339 format (i.e. `2019-12-06T22:35:49Z`) Format: `date-time` string The end datetime of bank transfers to list. This should be in RFC 3339 format (i.e. `2019-12-06T22:35:49Z`) Format: `date-time` string Plaid’s unique identifier for a bank transfer. string The account ID to get events for all transactions to/from an account. string The type of bank transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into your origination account; a `credit` indicates a transfer of money out of your origination account. Possible values: `debit`, `credit`, `null` \[string\] Filter events by event type. Possible values: `pending`, `cancelled`, `failed`, `posted`, `reversed` integer The maximum number of bank transfer events to return. If the number of events matching the above parameters is greater than `count`, the most recent events will be returned. Default: `25` Maximum: `25` Minimum: `1` integer The offset into the list of bank transfer events. When `count`\=25 and `offset`\=0, the first 25 events will be returned. When `count`\=25 and `offset`\=25, the next 25 bank transfer events will be returned. Default: `0` Minimum: `0` string The origination account ID to get events for transfers from a specific origination account. string Indicates the direction of the transfer: `outbound`: for API-initiated transfers `inbound`: for payments received by the FBO account. Possible values: `inbound`, `outbound`, `null` ```bash curl -X POST https://sandbox.plaid.com/bank_transfer/event/list \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "start_date": String, "end_date": String, "bank_transfer_id": String, "account_id": String, "bank_transfer_type": String, "event_types": [String], "count": Number, "offset": Number, "origination_account_id": String, "direction": String }' ``` ```python request = BankTransferEventListRequest( start_date=start_date, end_date=end_date, bank_transfer_id=bank_transfer_id, account_id=account_id, bank_transfer_type=bank_transfer_type, event_types=event_types, count=count, offset=offset, origination_account_id=origination_account_id, direction=direction, ) response = client.bank_transfer_event_list(request) events = response['bank_transfer_events'] for event in events: # iterate through events ``` ```node const request: BankTransferEventListRequest = { start_date: start_date, end_date: end_date, bank_transfer_id: bank_transfer_id, account_id: account_id, bank_transfer_type: bank_transfer_type, event_types: event_types, count: count, offset: offset, origination_account_id: origination_account_id, direction: direction, }; try { const response = await plaidClient.bankTransferEventList(request); const events = response.data.bank_transfer_events; for (const event of events) { // iterate through events } } catch (error) { // handle error } ``` ```java BankTransferEventListRequest request = new BankTransferEventListRequest() .bankTransferId(bankTransferId) .startDate(startDate) .endDate(endDate) .accountId(accountId) .bankTransferType(bankTransferType) .eventTypes(eventTypes) .count(count) .offset(offset) .originationAccountId(originationAccountId) .direction(direction); Response response = client() .bankTransferEventList(request) .execute(); List bankTransferEvents = response.body().getBankTransferEvents(); for (BankTransferEvent e : bankTransferEvents) { // iterate through events } ``` ```ruby request = Plaid::BankTransferEventListRequest.new( { start_date: start_date, end_date: end_date, bank_transfer_id: bank_transfer_id, account_id: account_id, bank_transfer_type: bank_transfer_type, event_types: event_types, count: count, offset: offset, origination_account_id: origination_account_id, direction: direction, } ) response = client.bank_transfer_event_list(request) response.bank_transfer_events.each do |event| # iterate through events end ``` ```go request := plaid.NewBankTransferEventListRequest() response, _, err := client.PlaidApi.BankTransferEventList(ctx).BankTransferEventListRequest(*request).Execute() ``` #### Response fields  \[object\] integer Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers. Minimum: `0` string The datetime when this event occurred. This will be of the form `2006-01-02T15:04:05Z`. Format: `date-time` string The type of event that this bank transfer represents. `pending`: A new transfer was created; it is in the pending state. `cancelled`: The transfer was cancelled by the client. `failed`: The transfer failed, no funds were moved. `posted`: The transfer has been successfully submitted to the payment network. `reversed`: A posted transfer was reversed. Possible values: `pending`, `cancelled`, `failed`, `posted`, `reversed` string The account ID associated with the bank transfer. string Plaid’s unique identifier for a bank transfer. nullable, string The ID of the origination account that this balance belongs to. string The type of bank transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `debit`, `credit` string The bank transfer amount. string The currency of the bank transfer amount. nullable, object The failure reason if the type of this transfer is `"failed"` or `"reversed"`. Null value otherwise. nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `reversed`. For a full listing of ACH return codes, see [Bank Transfers errors](https://plaid.com/docs/errors/bank-transfers/index.html.md#ach-return-codes) . string A human-readable description of the reason for the failure or reversal. nullable, string Indicates the direction of the transfer: `outbound` for API-initiated transfers, or `inbound` for payments received by the FBO account. Possible values: `outbound`, `inbound`, `null` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "bank_transfer_events": [ { "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B", "bank_transfer_amount": "12.34", "bank_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "bank_transfer_iso_currency_code": "USD", "bank_transfer_type": "credit", "direction": "outbound", "event_id": 1, "event_type": "pending", "failure_reason": null, "origination_account_id": "", "timestamp": "2020-08-06T17:27:15Z" } ], "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /bank\_transfer/event/sync  #### Sync bank transfer events  [/bank\_transfer/event/sync](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventsync) allows you to request up to the next 25 Plaid-initiated bank transfer events that happened after a specific `event_id`. When using Auth with micro-deposit verification enabled, this endpoint can be used to fetch status updates on ACH micro-deposits. For more details, see [micro-deposit events](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, integer The latest (largest) `event_id` fetched via the sync endpoint, or 0 initially. Minimum: `0` integer The maximum number of bank transfer events to return. Default: `25` Minimum: `1` Maximum: `25` ```bash curl -X POST https://sandbox.plaid.com/bank_transfer/event/sync \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "after_id": Number, "count": Number }' ``` ```python request = BankTransferEventSyncRequest( after_id=after_id, count=count ) response = client.bank_transfer_event_sync(request) events = response["bank_transfer_events"] for event in events: # iterate through events ``` ```node const request: BankTransferEventSyncRequest = { after_id: afterID, count: 25, }; try { const response = await plaidClient.bankTransferEventSync(request); const events = response.data.bank_transfer_events; for (const event of events) { // iterate through events } } catch (error) { // handle error } ``` ```java BankTransferEventSyncRequest request = new BankTransferEventSyncRequest() .afterId(0) .count(count); Response response = client() .bankTransferEventSync(request) .execute(); List bankTransferEvents = response.body().getBankTransferEvents(); for (BankTransferEvent e : bankTransferEvents) { // iterate through events } ``` ```ruby request = Plaid::BankTransferEventSyncRequest.new({ after_id: 0 }) response = client.bank_transfer_event_sync(request) response.bank_transfer_events.each do |event| # iterate through events end ``` ```go request := plaid.NewBankTransferEventSyncRequest( 0, // after_id ) response, _, err := client.PlaidApi.BankTransferEventSync(ctx).BankTransferEventSyncRequest(*request).Execute() ``` #### Response fields  \[object\] integer Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers. Minimum: `0` string The datetime when this event occurred. This will be of the form `2006-01-02T15:04:05Z`. Format: `date-time` string The type of event that this bank transfer represents. `pending`: A new transfer was created; it is in the pending state. `cancelled`: The transfer was cancelled by the client. `failed`: The transfer failed, no funds were moved. `posted`: The transfer has been successfully submitted to the payment network. `reversed`: A posted transfer was reversed. Possible values: `pending`, `cancelled`, `failed`, `posted`, `reversed` string The account ID associated with the bank transfer. string Plaid’s unique identifier for a bank transfer. nullable, string The ID of the origination account that this balance belongs to. string The type of bank transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `debit`, `credit` string The bank transfer amount. string The currency of the bank transfer amount. nullable, object The failure reason if the type of this transfer is `"failed"` or `"reversed"`. Null value otherwise. nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `reversed`. For a full listing of ACH return codes, see [Bank Transfers errors](https://plaid.com/docs/errors/bank-transfers/index.html.md#ach-return-codes) . string A human-readable description of the reason for the failure or reversal. nullable, string Indicates the direction of the transfer: `outbound` for API-initiated transfers, or `inbound` for payments received by the FBO account. Possible values: `outbound`, `inbound`, `null` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "bank_transfer_events": [ { "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B", "bank_transfer_amount": "12.34", "bank_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "bank_transfer_iso_currency_code": "USD", "bank_transfer_type": "credit", "direction": "outbound", "event_id": 1, "event_type": "pending", "failure_reason": null, "origination_account_id": "", "timestamp": "2020-08-06T17:27:15Z" } ], "request_id": "mdqfuVxeoza6mhu" } ``` ### Webhooks  Updates are sent for Items that are linked using micro-deposits (excluding Instant Micro-deposits). When an automated micro-deposit is created, Plaid sends a webhook upon successful verification. If verification does not succeed after seven days for an automated micro-deposit, Plaid sends a `VERIFICATION_EXPIRED` webhook. If you attempt to retrieve an automated micro-deposit Item before verification succeeds, you'll receive a response with the HTTP status code 400 and a Plaid error code of `PRODUCT_NOT_READY`. For Same-Day micro-deposits, Plaid does not send `AUTOMATICALLY_VERIFIED` or `VERIFICATION_EXPIRED` webhooks, but you may instead use the `BANK_TRANSFERS_EVENTS_UPDATE` webhook to [access the underlying ACH events](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) of micro-deposits. Plaid will trigger a `DEFAULT_UPDATE` webhook for Items that undergo a change in Auth data. This is a rare event and is generally caused by data partners notifying Plaid of a change in their account numbering system or to their routing numbers. To avoid returned transactions, customers that receive a `DEFAULT_UPDATE` webhook with the `account_ids_with_updated_auth` object populated should immediately discontinue all usages of existing Auth data for those accounts and call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) to obtain updated account and routing numbers. \=\*=\*=\*= #### DEFAULT\_UPDATE  Plaid will trigger a `DEFAULT_UPDATE` webhook for Items that undergo a change in Auth data. This is generally caused by data partners notifying Plaid of a change in their account numbering system or to their routing numbers. To avoid returned transactions, customers that receive a `DEFAULT_UPDATE` webhook with the `account_ids_with_updated_auth` object populated should immediately discontinue all usages of existing Auth data for those accounts and call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) to obtain updated account and routing numbers. #### Properties  string `AUTH` string `DEFAULT_UPDATE` string The `item_id` of the Item associated with this webhook, warning, or error \[string\] An array of `account_id`'s for accounts that contain new auth. object An object with keys of `account_id`'s that are mapped to their respective auth attributes that changed. `ACCOUNT_NUMBER` and `ROUTING_NUMBER` are the two potential values that can be flagged as updated. Example: `{ "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": ["ACCOUNT_NUMBER"] }` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "AUTH", "webhook_code": "DEFAULT_UPDATE", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "account_ids_with_updated_auth": { "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp": [ "ACCOUNT_NUMBER" ] }, "error": null, "environment": "production" } ``` \=\*=\*=\*= #### AUTOMATICALLY\_VERIFIED  Fired when an Item is verified via automated micro-deposits. We recommend communicating to your users when this event is received to notify them that their account is verified and ready for use. #### Properties  string `AUTH` string `AUTOMATICALLY_VERIFIED` string The `account_id` of the account associated with the webhook string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. API Object ```json { "webhook_type": "AUTH", "webhook_code": "AUTOMATICALLY_VERIFIED", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "environment": "production", "error": null } ``` \=\*=\*=\*= #### VERIFICATION\_EXPIRED  Fired when an Item was not verified via automated micro-deposits after seven days since the automated micro-deposit was made. #### Properties  string `AUTH` string `VERIFICATION_EXPIRED` string The `item_id` of the Item associated with this webhook, warning, or error string The `account_id` of the account associated with the webhook string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. API Object ```json { "webhook_type": "AUTH", "webhook_code": "VERIFICATION_EXPIRED", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "environment": "production", "error": null } ``` \=\*=\*=\*= #### BANK\_TRANSFERS\_EVENTS\_UPDATE  Fired when new ACH events are available. To begin receiving this webhook, you must first register your webhook listener endpoint via the [webhooks page in the Dashboard](https://dashboard.plaid.com/team/webhooks) . The `BANK_TRANSFERS_EVENTS_UPDATE` webhook can be used to track the progress of ACH transfers used in [micro-deposit verification](https:///docs/auth/coverage/microdeposit-events/) . Receiving this webhook indicates you should fetch the new events from [/bank\_transfer/event/sync](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventsync) . Note that [Transfer](https://plaid.com/docs/transfer/index.html.md) customers should use Transfer webhooks instead of using `BANK_TRANSFERS_EVENTS_UPDATE`; see [micro-deposit events documentation](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) for more details. #### Properties  string `BANK_TRANSFERS` string `BANK_TRANSFERS_EVENTS_UPDATE` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "BANK_TRANSFERS", "webhook_code": "BANK_TRANSFERS_EVENTS_UPDATE", "environment": "production" } ``` \=\*=\*=\*= #### SMS\_MICRODEPOSITS\_VERIFICATION  Contains the state of a SMS same-day microdeposits verification session. #### Properties  string `AUTH` string `SMS_MICRODEPOSITS_VERIFICATION` string The final status of the same-day microdeposits verification. Will always be `MANUALLY_VERIFIED` or `VERIFICATION_FAILED`. string The `item_id` of the Item associated with this webhook, warning, or error string The external account ID of the affected account string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "AUTH", "webhook_code": "SMS_MICRODEPOSITS_VERIFICATION", "status": "MANUALLY_VERIFIED", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "environment": "sandbox" } ``` --- # API - Beacon (beta) | Plaid Docs Beacon  ======= #### API reference for Beacon endpoints and webhooks  Add and report users on the Plaid Beacon network. | Endpoints | | | --- | --- | | [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) | Create and scan a Beacon User against a Beacon Program | | [/beacon/user/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserget) | Fetch a Beacon User | | [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) | Update and rescan a Beacon User | | [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) | Fetch a Beacon User's account insights | | [/beacon/user/history/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserhistorylist) | List a Beacon User's history | | [/beacon/report/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportcreate) | Create a fraud report for a given Beacon User | | [/beacon/report/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportget) | Fetch a Beacon Report | | [/beacon/report/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportlist) | List Beacon Reports for a given Beacon User | | [/beacon/report\_syndication/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationget) | Fetch a Beacon Report Syndication | | [/beacon/report\_syndication/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationlist) | List Beacon Report Syndications for a given Beacon User | | [/beacon/duplicate/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconduplicateget) | Fetch a Beacon duplicate | | See also | | | --- | --- | | [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) | Retrieve information about a dashboard user | | [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) | List dashboard users | | Webhooks | | | --- | --- | | [USER\_STATUS\_UPDATED](https://plaid.com/docs/api/products/beacon/index.html.md#user_status_updated) | Beacon User status has changed | | [REPORT\_CREATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_created) | Beacon Report has been created | | [REPORT\_UPDATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_updated) | Beacon Report has been updated | | [REPORT\_SYNDICATION\_CREATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_syndication_created) | New Network Report matches one of your Users | | [DUPLICATE\_DETECTED](https://plaid.com/docs/api/products/beacon/index.html.md#duplicate_detected) | Duplicate Beacon User was created | \=\*=\*=\*= #### /beacon/user/create  This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### Create a Beacon User  Create and scan a Beacon User against your Beacon Program, according to your program's settings. When you submit a new user to [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) , several checks are performed immediately: * The user's PII (provided within the `user` object) is searched against all other users within the Beacon Program you specified. If a match is found that violates your program's "Duplicate Information Filtering" settings, the user will be returned with a status of `pending_review`. * The user's PII is also searched against all fraud reports created by your organization across all of your Beacon Programs. If the user's data matches a fraud report that your team created, the user will be returned with a status of `rejected`. * Finally, the user's PII is searched against all fraud report shared with the Beacon Network by other companies. If a matching fraud report is found, the user will be returned with a `pending_review` status if your program has enabled automatic flagging based on network fraud. #### Request fields  required, string ID of the associated Beacon Program. required, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. required, object A Beacon User's data which is used to check against duplicate records and the Beacon Fraud Network. In order to create a Beacon User, in addition to the `name`, \_either\_ the `date_of_birth` \_or\_ the `depository_accounts` field must be provided. string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` required, object The full name for a given Beacon User. required, string A string with at least one non-whitespace character, with a max length of 100 characters. required, string A string with at least one non-whitespace character, with a max length of 100 characters. object Home address for the associated user. For more context on this field, see [Input Validation by Country](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#input-validation-by-country) . required, string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. required, string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. required, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` string A phone number in E.164 format. object The ID number associated with a Beacon User. required, string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . required, string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` string An IPv4 or IPV6 address. \[object\] Provide a list of bank accounts that are associated with this Beacon User. These accounts will be scanned across the Beacon Network and used to find duplicate records. Note: These accounts will not have Bank Account Insights. To receive Bank Account Insights please supply `access_tokens`. required, string Must be a valid US Bank Account Number required, string The routing number of the account. \[string\] Send this array of access tokens to link accounts to the Beacon User and have them evaluated for Account Insights. A maximum of 50 accounts total can be added to a single Beacon User. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```ruby request = Plaid::BeaconUserCreateRequest.new( { program_id: 'becprg_11111111111111', client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', access_tokens: [access_token], user: Plaid::BeaconUserRequestData.new( { email_address: 'user@example.com', date_of_birth: '1975-01-18', name: Plaid::BeaconUserName.new( { given_name: 'Leslie', family_name: 'Knope' } ), address: Plaid::BeaconUserAddress.new( { street: '123 Main St.', street2: 'Unit 42', city: 'Pawnee', region: 'IN', postal_code: '46001', country: 'US' } ) } ) } ) ``` ```bash curl -X POST https://sandbox.plaid.com/beacon/user/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "program_id": "becprg_11111111111111", "client_user_id": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", "access_tokens": ["${ACCESS_TOKEN}"], "user": { "email_address": "user@example.com", "date_of_birth": "1975-01-18", "name": { "given_name": "Leslie", "family_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" } } }' ``` ```node const request: BeaconUserCreateRequest = { program_id: 'becprg_11111111111111', client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', access_tokens: [access_token], user: { email_address: 'user@example.com', date_of_birth: '1975-01-18', name: { given_name: 'Leslie', family_name: 'Knope', }, address: { street: '123 Main St.', street2: 'Unit 42', city: 'Pawnee', region: 'IN', postal_code: '46001', country: 'US', }, }, }; try { const response = await plaidClient.beaconUserCreate(request); console.log(response.status.value); } catch (error) { // handle error } ``` ```java LocalDate dobBeacon = LocalDate.parse("1975-01-18"); BeaconUserName beaconUserName = new BeaconUserName() .givenName("Leslie") .familyName("Knope"); BeaconUserAddress beaconUserAddress = new BeaconUserAddress() .street("123 Main St.") .street2("Unit 42") .city("Pawnee") .region("IN") .postalCode("46001") .country("US"); BeaconUserRequestData beaconUserRequestData = new BeaconUserRequestData() .emailAddress("user@example.com") .dateOfBirth(dobBeacon) .name(beaconUserName) .address(beaconUserAddress); BeaconUserCreateRequest beaconUserCreateRequest = new BeaconUserCreateRequest() .programId("becprg_11111111111111") .clientUserId("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d") .accessTokens(accessTokens) .user(beaconUserRequestData); Response beaconResponse = client.beaconUserCreate(beaconUserCreateRequest).execute(); String statusValue = beaconResponse.body().getStatus().getValue(); ``` ```python client = create_client() request = BeaconUserCreateRequest( program_id='becprg_11111111111111', client_user_id=ClientUserID('user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d'), access_tokens=[access_token], user=BeaconUserRequestData( email_address='user@example.com', date_of_birth='1975-01-18', name=BeaconUserName( given_name='Leslie', family_name='Knope' ), address=BeaconUserAddress( street='123 Main St.', street2='Unit 42', city='Pawnee', region='IN', postal_code='46001', country='US' ) ) ) response = client.beacon_user_create(request) response.status.value ``` ```go user := plaid.NewBeaconUserRequestData() user.SetEmailAddress("user@example.com") user.SetDateOfBirth("1975-01-18") user.SetName( *plaid.NewBeaconUserName( "Leslie", "Knope", ), ) user.SetAddress( *plaid.NewBeaconUserAddress( "123 Main St.", "Unit 42", "Pawnee", "IN", "46001", "US", ), ) request := plaid.NewBeaconUserCreateRequest( "becprg_11111111111111", ) request.SetClientUserId("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d") request.SetUser(*user) request.SetAccessTokens(*accessTokens) response, _, err := client.PlaidApi. BeaconUserCreate(ctx). BeaconUserCreateRequest(*request). Execute() statusValue := response.GetStatus().GetValue() ``` #### Response fields  \[string\] An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User. string ID of the associated Beacon User. integer The `version` field begins with 1 and increments each time the user is updated. string An ISO8601 formatted timestamp. Format: `date-time` string An ISO8601 formatted timestamp. This field indicates the last time the resource was modified. Format: `date-time` string A status of a Beacon User. `rejected`: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected. `pending_review`: The Beacon User has been marked for review. `cleared`: The Beacon User has been cleared of fraud. Possible values: `rejected`, `pending_review`, `cleared` string ID of the associated Beacon Program. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network. string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` object The full name for a given Beacon User. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. object Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include a postal code string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. nullable, string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, string A phone number in E.164 format. nullable, object The ID number associated with a Beacon User. string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` nullable, string An IPv4 or IPV6 address. \[object\] string The last 2-4 numeric characters of this account’s account number. string The routing number of the account. string An ISO8601 formatted timestamp. Format: `date-time` object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating what caused a resource to be changed or updated. `dashboard` - The resource was created or updated by a member of your team via the Plaid dashboard. `api` - The resource was created or updated via the Plaid API. `system` - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be `system`. `bulk_import` - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be `bulk_import`. Possible values: `dashboard`, `api`, `system`, `bulk_import` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "item_ids": [ "515cd85321d3649aecddc015" ], "id": "becusr_42cF1MNo42r9Xj", "version": 1, "created_at": "2020-07-24T03:26:02Z", "updated_at": "2020-07-24T03:26:02Z", "status": "cleared", "program_id": "becprg_11111111111111", "client_user_id": "your-db-id-3b24110", "user": { "date_of_birth": "1990-05-29", "name": { "given_name": "Leslie", "family_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "email_address": "user@example.com", "phone_number": "+19876543212", "id_number": { "value": "123456789", "type": "us_ssn" }, "ip_address": "192.0.2.42", "depository_accounts": [ { "account_mask": "4000", "routing_number": "021000021", "added_at": "2020-07-24T03:26:02Z" } ] }, "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /beacon/user/get  This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### Get a Beacon User  Fetch a Beacon User. The Beacon User is returned with all of their associated information and a `status` based on the Beacon Network duplicate record and fraud checks. #### Request fields  required, string ID of the associated Beacon User. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```ruby client = create_client() request = Plaid::BeaconUserGetRequest.new( { beacon_user_id: 'becusr_11111111111111' } ) response = client.beacon_user_get(request) ``` ```bash curl -X POST https://sandbox.plaid.com/beacon/user/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "beacon_user_id": "becusr_11111111111111" }' ``` ```node const request: BeaconUserGetRequest = { beacon_user_id: 'becusr_11111111111111', }; try { const response = await plaidClient.beaconUserGet(request); } catch (error) { // handle error } ``` ```java BeaconUserGetRequest request = new BeaconUserGetRequest().beaconUserId("becusr_11111111111111"); Response response = client.beaconUserGet(request).execute(); ``` ```python client = create_client() request = BeaconUserGetRequest(beacon_user_id='becusr_11111111111111') response = client.beacon_user_get(request) ``` ```go request := plaid.NewBeaconUserGetRequest("becusr_11111111111111") response, _, err := client.PlaidApi. BeaconUserGet(ctx). BeaconUserGetRequest(*request). Execute() ``` #### Response fields  \[string\] An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User. string ID of the associated Beacon User. integer The `version` field begins with 1 and increments each time the user is updated. string An ISO8601 formatted timestamp. Format: `date-time` string An ISO8601 formatted timestamp. This field indicates the last time the resource was modified. Format: `date-time` string A status of a Beacon User. `rejected`: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected. `pending_review`: The Beacon User has been marked for review. `cleared`: The Beacon User has been cleared of fraud. Possible values: `rejected`, `pending_review`, `cleared` string ID of the associated Beacon Program. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network. string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` object The full name for a given Beacon User. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. object Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include a postal code string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. nullable, string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, string A phone number in E.164 format. nullable, object The ID number associated with a Beacon User. string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` nullable, string An IPv4 or IPV6 address. \[object\] string The last 2-4 numeric characters of this account’s account number. string The routing number of the account. string An ISO8601 formatted timestamp. Format: `date-time` object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating what caused a resource to be changed or updated. `dashboard` - The resource was created or updated by a member of your team via the Plaid dashboard. `api` - The resource was created or updated via the Plaid API. `system` - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be `system`. `bulk_import` - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be `bulk_import`. Possible values: `dashboard`, `api`, `system`, `bulk_import` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "item_ids": [ "515cd85321d3649aecddc015" ], "id": "becusr_42cF1MNo42r9Xj", "version": 1, "created_at": "2020-07-24T03:26:02Z", "updated_at": "2020-07-24T03:26:02Z", "status": "cleared", "program_id": "becprg_11111111111111", "client_user_id": "your-db-id-3b24110", "user": { "date_of_birth": "1990-05-29", "name": { "given_name": "Leslie", "family_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "email_address": "user@example.com", "phone_number": "+19876543212", "id_number": { "value": "123456789", "type": "us_ssn" }, "ip_address": "192.0.2.42", "depository_accounts": [ { "account_mask": "4000", "routing_number": "021000021", "added_at": "2020-07-24T03:26:02Z" } ] }, "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /beacon/user/update  This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### Update the identity data of a Beacon User  Update the identity data for a Beacon User in your Beacon Program or add new accounts to the Beacon User. Similar to [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) , several checks are performed immediately when you submit an identity data change to [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) : * The user's updated PII is searched against all other users within the Beacon Program you specified. If a match is found that violates your program's "Duplicate Information Filtering" settings, the user will be returned with a status of `pending_review`. * The user's updated PII is also searched against all fraud reports created by your organization across all of your Beacon Programs. If the user's data matches a fraud report that your team created, the user will be returned with a status of `rejected`. * Finally, the user's PII is searched against all fraud report shared with the Beacon Network by other companies. If a matching fraud report is found, the user will be returned with a `pending_review` status if your program has enabled automatic flagging based on network fraud. Plaid maintains a version history for each Beacon User, so the Beacon User's identity data before and after the update is retained as separate versions. #### Request fields  required, string ID of the associated Beacon User. object A subset of a Beacon User's data which is used to patch the existing identity data associated with a Beacon User. At least one field must be provided. If left unset or null, user data will not be patched. string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` object The full name for a given Beacon User. required, string A string with at least one non-whitespace character, with a max length of 100 characters. required, string A string with at least one non-whitespace character, with a max length of 100 characters. object Home address for the associated user. For more context on this field, see [Input Validation by Country](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#input-validation-by-country) . required, string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. required, string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. required, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` string A phone number in E.164 format. object The ID number associated with a Beacon User. required, string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . required, string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` string An IPv4 or IPV6 address. \[object\] required, string Must be a valid US Bank Account Number required, string The routing number of the account. \[string\] Send this array of access tokens to add accounts to this user for evaluation. This will add accounts to this Beacon User. If left null only existing accounts will be returned in response. A maximum of 50 accounts total can be added to a Beacon User. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```ruby client = create_client() request = Plaid::BeaconUserUpdateRequest.new( { beacon_user_id: 'becusr_11111111111111', user: Plaid::BeaconUserUpdateRequestData.new( { email_address: 'user@example.com', date_of_birth: '1975-01-18', name: Plaid::BeaconUserName.new( { given_name: 'Leslie', family_name: 'Knope' } ), address: Plaid::BeaconUserAddress.new( { street: '123 Main St.', street2: 'Unit 42', city: 'Pawnee', region: 'IN', postal_code: '46001', country: 'US' } ) } ) } ) response = client.beacon_user_update(request) ``` ```bash curl -X POST https://sandbox.plaid.com/beacon/user/update \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "beacon_user_id": "becusr_11111111111111", "user": { "email_address": "user@example.com", "date_of_birth": "1975-01-18", "name": { "given_name": "Leslie", "family_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" } } }' ``` ```node const request: BeaconUserUpdateRequest = { beacon_user_id: 'becusr_11111111111111', user: { email_address: 'user@example.com', date_of_birth: '1975-01-18', name: { given_name: 'Leslie', family_name: 'Knope', }, address: { street: '123 Main St.', street2: 'Unit 42', city: 'Pawnee', region: 'IN', postal_code: '46001', country: 'US', }, }, }; try { const response = await plaidClient.beaconUserUpdate(request); console.log(response.status.value); } catch (error) { // handle error } ``` ```java BeaconUserName beaconUserName = new BeaconUserName() .givenName("Leslie") .familyName("Knope"); BeaconUserAddress beaconUserAddress = new BeaconUserAddress() .street("123 Main St.") .street2("Unit 42") .city("Pawnee") .region("IN") .postalCode("46001") .country("US"); BeaconUserUpdateRequestData beaconUserUpdateRequestData = new BeaconUserUpdateRequestData() .emailAddress("user@example.com") .dateOfBirth("1975-01-18") .name(beaconUserName) .address(beaconUserAddress); BeaconUserUpdateRequest beaconUserUpdateRequest = new BeaconUserUpdateRequest() .beaconUserId("becusr_11111111111111") .user(beaconUserUpdateRequestData); Response beaconResponse = client.beaconUserUpdate(beaconUserUpdateRequest).execute(); // You can access the response data here // For example: // String statusValue = beaconResponse.body().getStatus().getValue(); ``` ```python client = create_client() request = BeaconUserUpdateRequest( beacon_user_id='becusr_11111111111111', user=BeaconUserUpdateRequestData( email_address='user@example.com', date_of_birth='1975-01-18', name=BeaconUserName( given_name='Leslie', family_name='Knope' ), address=BeaconUserAddress( street='123 Main St.', street2='Unit 42', city='Pawnee', region='IN', postal_code='46001', country='US' ) ) ) response = client.beacon_user_update(request) ``` ```go user := plaid.NewBeaconUserUpdateRequestData() user.SetEmailAddress("user@example.com") user.SetDateOfBirth("1975-01-18") user.SetName( *plaid.NewBeaconUserName( "Leslie", "Knope", ), ) user.SetAddress( *plaid.NewBeaconUserAddress( "123 Main St.", "Unit 42", "Pawnee", "IN", "46001", "US", ), ) request := plaid.NewBeaconUserUpdateRequest( "becusr_11111111111111", ) request.SetUser(*user) response, _, err := client.PlaidApi. BeaconUserUpdate(ctx). BeaconUserUpdateRequest(*request). Execute() // You can access the response data here // For example: // statusValue := response.GetStatus().GetValue() ``` #### Response fields  \[string\] An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User. string ID of the associated Beacon User. integer The `version` field begins with 1 and increments each time the user is updated. string An ISO8601 formatted timestamp. Format: `date-time` string An ISO8601 formatted timestamp. This field indicates the last time the resource was modified. Format: `date-time` string A status of a Beacon User. `rejected`: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected. `pending_review`: The Beacon User has been marked for review. `cleared`: The Beacon User has been cleared of fraud. Possible values: `rejected`, `pending_review`, `cleared` string ID of the associated Beacon Program. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network. string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` object The full name for a given Beacon User. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. object Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include a postal code string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. nullable, string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, string A phone number in E.164 format. nullable, object The ID number associated with a Beacon User. string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` nullable, string An IPv4 or IPV6 address. \[object\] string The last 2-4 numeric characters of this account’s account number. string The routing number of the account. string An ISO8601 formatted timestamp. Format: `date-time` object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating what caused a resource to be changed or updated. `dashboard` - The resource was created or updated by a member of your team via the Plaid dashboard. `api` - The resource was created or updated via the Plaid API. `system` - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be `system`. `bulk_import` - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be `bulk_import`. Possible values: `dashboard`, `api`, `system`, `bulk_import` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "item_ids": [ "515cd85321d3649aecddc015" ], "id": "becusr_42cF1MNo42r9Xj", "version": 1, "created_at": "2020-07-24T03:26:02Z", "updated_at": "2020-07-24T03:26:02Z", "status": "cleared", "program_id": "becprg_11111111111111", "client_user_id": "your-db-id-3b24110", "user": { "date_of_birth": "1990-05-29", "name": { "given_name": "Leslie", "family_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "email_address": "user@example.com", "phone_number": "+19876543212", "id_number": { "value": "123456789", "type": "us_ssn" }, "ip_address": "192.0.2.42", "depository_accounts": [ { "account_mask": "4000", "routing_number": "021000021", "added_at": "2020-07-24T03:26:02Z" } ] }, "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /beacon/user/account\_insights/get  This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### Get Account Insights for a Beacon User  Get Account Insights for all Accounts linked to this Beacon User. The insights for each account are computed based on the information that was last retrieved from the financial institution. #### Request fields  required, string ID of the associated Beacon User. required, string The access token associated with the Item data is being requested for. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```ruby client = create_client() request = Plaid::BeaconUserAccountInsightsGetRequest.new( { beacon_user_id: 'becusr_11111111111111', access_token: 'access-sandbox-12345678', client_id: ENV['PLAID_CLIENT_ID'], secret: ENV['PLAID_SECRET'] } ) response = client.beacon_user_account_insights_get(request) ``` ```bash curl -X POST https://sandbox.plaid.com/beacon/user/account_insights/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "beacon_user_id": "becusr_11111111111111", "access_token": "access-sandbox-12345678" }' ``` ```node const request: BeaconUserAccountInsightsGetRequest = { beacon_user_id: 'becusr_11111111111111', access_token: 'access-sandbox-12345678', client_id: process.env.PLAID_CLIENT_ID, secret: process.env.PLAID_SECRET, }; try { const response = await plaidClient.beaconUserAccountInsightsGet(request); console.log(response.status.value); } catch (error) { // handle error } ``` ```java BeaconUserAccountInsightsGetRequest request = new BeaconUserAccountInsightsGetRequest() .beaconUserId("becusr_11111111111111") .accessToken("access-sandbox-12345678") .clientId(System.getenv("PLAID_CLIENT_ID")) .secret(System.getenv("PLAID_SECRET")); Response response = client.beaconUserAccountInsightsGet(request).execute(); ``` ```python client = create_client() request = BeaconUserAccountInsightsGetRequest( beacon_user_id='becusr_11111111111111', access_token='access-sandbox-12345678', client_id=os.getenv('PLAID_CLIENT_ID'), secret=os.getenv('PLAID_SECRET') ) response = client.beacon_user_account_insights_get(request) ``` ```go request := plaid.NewBeaconUserAccountInsightsGetRequest( "becusr_11111111111111", "access-sandbox-12345678", ) request.SetClientId(os.Getenv("PLAID_CLIENT_ID")) request.SetSecret(os.Getenv("PLAID_SECRET")) response, _, err := client.PlaidApi. BeaconUserAccountInsightsGet(ctx). BeaconUserAccountInsightsGetRequest(*request). Execute() statusValue := response.GetStatus().GetValue() ``` #### Response fields  string ID of the associated Beacon User. string An ISO8601 formatted timestamp. Format: `date-time` string An ISO8601 formatted timestamp. This field indicates the last time the resource was modified. Format: `date-time` object A collection of Bank Accounts linked to an Item that is associated with this Beacon User. string The Plaid Item ID the Bank Accounts belong to. \[object\] string The Plaid `account_id` string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` object The attributes object contains data that can be used to assess account risk. Examples of data include: `days_since_first_plaid_connection`: The number of days since the first time the Item was connected to an application via Plaid `plaid_connections_count_7d`: The number of times the Item has been connected to applications via Plaid over the past 7 days `plaid_connections_count_30d`: The number of times the Item has been connected to applications via Plaid over the past 30 days `total_plaid_connections_count`: The number of times the Item has been connected to applications via Plaid For the full list and detailed documentation of core attributes available, or to request that core attributes not be returned, contact Sales or your Plaid account manager nullable, integer The number of days since the first time the Item was connected to an application via Plaid nullable, boolean Indicates if the account has been closed by the financial institution or the consumer, or is at risk of being closed nullable, boolean Indicates whether the account has withdrawals and transfers disabled or if access to the account is restricted. This could be due to a freeze by the credit issuer, legal restrictions (e.g., sanctions), or regulatory requirements limiting monthly withdrawals, among other reasons nullable, integer The total number of times the item has been connected to applications via Plaid nullable, integer The number of times the Item has been connected to applications via Plaid over the past 7 days nullable, integer The number of times the Item has been connected to applications via Plaid over the past 30 days nullable, integer The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 3 days nullable, integer The number of non-OAuth authentication attempts via Plaid for this bank account over the past 3 days nullable, integer The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 7 days nullable, integer The number of non-OAuth authentication attempts via Plaid for this bank account over the past 7 days nullable, integer The number of failed non-OAuth authentication attempts via Plaid for this bank account over the past 30 days nullable, integer The number of non-OAuth authentication attempts via Plaid for this bank account over the past 30 days nullable, integer The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 3 days nullable, integer The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 7 days nullable, integer The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 30 days nullable, integer The number of distinct IP addresses linked to the same bank account during Plaid authentication in the last 90 days nullable, integer The number of distinct user agents linked to the same bank account during Plaid authentication in the last 3 days nullable, integer The number of distinct user agents linked to the same bank account during Plaid authentication in the last 7 days nullable, integer The number of distinct user agents linked to the same bank account during Plaid authentication in the last 30 days nullable, integer The number of distinct user agents linked to the same bank account during Plaid authentication in the last 90 days nullable, integer The number of times the account's addresses on file have changed over the past 28 days nullable, integer The number of times the account's email addresses on file have changed over the past 28 days nullable, integer The number of times the account's phone numbers on file have changed over the past 28 days nullable, integer The number of times the account's addresses on file have changed over the past 90 days nullable, integer The number of times the account's email addresses on file have changed over the past 90 days nullable, integer The number of times the account's phone numbers on file have changed over the past 90 days nullable, integer The number of days since the bank account was opened, as reported by the financial institution nullable, integer The number of days since the oldest transaction available to Plaid for this account. This measure, combined with Plaid connection history, can be used to infer the age of the account string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "beacon_user_id": "becusr_42cF1MNo42r9Xj", "created_at": "2020-07-24T03:26:02Z", "updated_at": "2020-07-24T03:26:02Z", "bank_account_insights": { "item_id": "515cd85321d3649aecddc015", "accounts": [ { "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo", "type": "depository", "subtype": "checking", "attributes": { "days_since_first_plaid_connection": 1, "is_account_closed": false, "is_account_frozen_or_restricted": false, "total_plaid_connections_count": 1, "plaid_connections_count_7d": 1, "plaid_connections_count_30d": 1, "failed_plaid_non_oauth_authentication_attempts_count_3d": 1, "plaid_non_oauth_authentication_attempts_count_3d": 1, "failed_plaid_non_oauth_authentication_attempts_count_7d": 1, "plaid_non_oauth_authentication_attempts_count_7d": 1, "failed_plaid_non_oauth_authentication_attempts_count_30d": 1, "plaid_non_oauth_authentication_attempts_count_30d": 1, "distinct_ip_addresses_count_3d": 1, "distinct_ip_addresses_count_7d": 1, "distinct_ip_addresses_count_30d": 1, "distinct_ip_addresses_count_90d": 1, "distinct_user_agents_count_3d": 1, "distinct_user_agents_count_7d": 1, "distinct_user_agents_count_30d": 1, "distinct_user_agents_count_90d": 1, "address_change_count_28d": 1, "email_change_count_28d": 2, "phone_change_count_28d": 1, "address_change_count_90d": 3, "email_change_count_90d": 4, "phone_change_count_90d": 2, "days_since_account_opening": 365, "days_since_first_observed_transaction": 180 } } ] }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /beacon/user/history/list  This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### List a Beacon User's history  List all changes to the Beacon User in reverse-chronological order. #### Request fields  required, string ID of the associated Beacon User. string An identifier that determines which page of results you receive. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```ruby client = create_client() request = Plaid::BeaconUserHistoryListRequest.new( { beacon_user_id: 'becusr_11111111111111' } ) response = client.beacon_user_history_list(request) ``` ```bash curl -X POST https://sandbox.plaid.com/beacon/user/history/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "beacon_user_id": "becusr_11111111111111", }' ``` ```node const request: BeaconUserHistoryListRequest = { beacon_user_id: 'becusr_11111111111111', }; try { const response = await plaidClient.beaconUserHistoryList(request); } catch (error) { // handle error } ``` ```java BeaconUserHistoryListRequest request = new BeaconUserHistoryListRequest().beaconUserId("becusr_11111111111111"); Response response = client.beaconUserHistoryList(request).execute(); ``` ```python client = create_client() request = BeaconUserHistoryListRequest(beacon_user_id='becusr_11111111111111') response = client.beacon_user_history_list(request) ``` ```go request := plaid.NewBeaconUserHistoryListRequest("becusr_11111111111111") response, _, err := client.PlaidApi. BeaconUserHistoryList(ctx). BeaconUserHistoryListRequest(*request). Execute() ``` #### Response fields  \[object\] \[string\] An array of Plaid Item IDs corresponding to the Accounts associated with this Beacon User. string ID of the associated Beacon User. integer The `version` field begins with 1 and increments each time the user is updated. string An ISO8601 formatted timestamp. Format: `date-time` string An ISO8601 formatted timestamp. This field indicates the last time the resource was modified. Format: `date-time` string A status of a Beacon User. `rejected`: The Beacon User has been rejected for fraud. Users can be automatically or manually rejected. `pending_review`: The Beacon User has been marked for review. `cleared`: The Beacon User has been cleared of fraud. Possible values: `rejected`, `pending_review`, `cleared` string ID of the associated Beacon Program. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object A Beacon User's data and resulting analysis when checked against duplicate records and the Beacon Fraud Network. string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` object The full name for a given Beacon User. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. object Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include a postal code string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. nullable, string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, string A phone number in E.164 format. nullable, object The ID number associated with a Beacon User. string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` nullable, string An IPv4 or IPV6 address. \[object\] string The last 2-4 numeric characters of this account’s account number. string The routing number of the account. string An ISO8601 formatted timestamp. Format: `date-time` object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating what caused a resource to be changed or updated. `dashboard` - The resource was created or updated by a member of your team via the Plaid dashboard. `api` - The resource was created or updated via the Plaid API. `system` - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be `system`. `bulk_import` - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be `bulk_import`. Possible values: `dashboard`, `api`, `system`, `bulk_import` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "beacon_users": [ { "item_ids": [ "515cd85321d3649aecddc015" ], "id": "becusr_42cF1MNo42r9Xj", "version": 1, "created_at": "2020-07-24T03:26:02Z", "updated_at": "2020-07-24T03:26:02Z", "status": "cleared", "program_id": "becprg_11111111111111", "client_user_id": "your-db-id-3b24110", "user": { "date_of_birth": "1990-05-29", "name": { "given_name": "Leslie", "family_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "email_address": "user@example.com", "phone_number": "+19876543212", "id_number": { "value": "123456789", "type": "us_ssn" }, "ip_address": "192.0.2.42", "depository_accounts": [ { "account_mask": "4000", "routing_number": "021000021", "added_at": "2020-07-24T03:26:02Z" } ] }, "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /beacon/report/create  This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### Create a Beacon Report  Create a fraud report for a given Beacon User. #### Request fields  required, string ID of the associated Beacon User. required, string The type of Beacon Report. `first_party`: If this is the same individual as the one who submitted the KYC. `stolen`: If this is a different individual from the one who submitted the KYC. `synthetic`: If this is an individual using fabricated information. `account_takeover`: If this individual's account was compromised. `unknown`: If you aren't sure who committed the fraud. Possible values: `first_party`, `stolen`, `synthetic`, `account_takeover`, `unknown` required, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` object The amount and currency of the fraud or attempted fraud. `fraud_amount` should be omitted to indicate an unknown fraud amount. required, string An ISO-4217 currency code. Possible values: `USD` required, number The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., `1.23`). Format: `double` string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```ruby client = create_client() request = Plaid::BeaconReportCreateRequest.new( { beacon_user_id: 'becusr_11111111111111', type: Plaid::BeaconReportType::FIRST_PARTY, fraud_date: '1975-01-18' } ) response = client.beacon_report_create(request) ``` ```bash curl -X POST https://sandbox.plaid.com/beacon/report/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "beacon_user_id": "becusr_11111111111111", "type": "first_party", "fraud_date": "1975-01-18" }' ``` ```node const request: BeaconReportCreateRequest = { beacon_user_id: 'becusr_11111111111111', type: 'first_party', fraud_date: '1975-01-18', }; try { const response = await plaidClient.beaconReportCreate(request); } catch (error) { // handle error } ``` ```java Client client = createClient(); BeaconReportType reportType = BeaconReportType.FIRST_PARTY; BeaconReportCreateRequest request = new BeaconReportCreateRequest() .beaconUserId("becusr_11111111111111") .type(reportType) .fraudDate("1975-01-18"); Response response = client.beaconReportCreate(request).execute(); ``` ```python client = create_client() request = BeaconReportCreateRequest( beacon_user_id='becusr_11111111111111', type=BeaconReportType('first_party'), fraud_date='1975-01-18' ) response = client.beacon_report_create(request) ``` ```go request := plaid.NewBeaconReportCreateRequest( "becusr_11111111111111", plaid.BEACONREPORTTYPE_FIRST_PARTY, "1975-01-18", ) response, _, err := client.PlaidApi. BeaconReportCreate(ctx). BeaconReportCreateRequest(*request). Execute() ``` #### Response fields  string ID of the associated Beacon Report. string ID of the associated Beacon User. string An ISO8601 formatted timestamp. Format: `date-time` string The type of Beacon Report. `first_party`: If this is the same individual as the one who submitted the KYC. `stolen`: If this is a different individual from the one who submitted the KYC. `synthetic`: If this is an individual using fabricated information. `account_takeover`: If this individual's account was compromised. `data_breach`: If this individual's data was compromised in a breach. `unknown`: If you aren't sure who committed the fraud. Possible values: `first_party`, `stolen`, `synthetic`, `account_takeover`, `data_breach`, `unknown` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, object The amount and currency of the fraud or attempted fraud. `fraud_amount` should be omitted to indicate an unknown fraud amount. string An ISO-4217 currency code. Possible values: `USD` number The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., `1.23`). Format: `double` object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating what caused a resource to be changed or updated. `dashboard` - The resource was created or updated by a member of your team via the Plaid dashboard. `api` - The resource was created or updated via the Plaid API. `system` - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be `system`. `bulk_import` - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be `bulk_import`. Possible values: `dashboard`, `api`, `system`, `bulk_import` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "becrpt_11111111111111", "beacon_user_id": "becusr_42cF1MNo42r9Xj", "created_at": "2020-07-24T03:26:02Z", "type": "first_party", "fraud_date": "1990-05-29", "event_date": "1990-05-29", "fraud_amount": { "iso_currency_code": "USD", "value": 100 }, "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /beacon/report/get  This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### Get a Beacon Report  Returns a Beacon report for a given Beacon report id. #### Request fields  required, string ID of the associated Beacon Report. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```ruby client = create_client() request = Plaid::BeaconReportGetRequest.new( { beacon_report_id: 'becrpt_11111111111111' } ) response = client.beacon_report_get(request) ``` ```bash curl -X POST https://sandbox.plaid.com/beacon/report/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "beacon_report_id": "becrpt_11111111111111" }' ``` ```node const request: BeaconReportGetRequest = { beacon_report_id: 'becrpt_11111111111111', }; try { const response = await plaidClient.beaconReportGet(request); } catch (error) { // handle error } ``` ```java BeaconReportGetRequest request = new BeaconReportGetRequest() .beaconReportId("becrpt_11111111111111"); Response response = client.beaconReportGet(request).execute(); ``` ```python client = create_client() request = BeaconReportGetRequest( beacon_report_id='becrpt_11111111111111' ) response = client.beacon_report_get(request) ``` ```go request := plaid.NewBeaconReportGetRequest("becrpt_11111111111111") response, _, err := client.PlaidApi. BeaconReportGet(ctx). BeaconReportGetRequest(*request). Execute() ``` #### Response fields  string ID of the associated Beacon Report. string ID of the associated Beacon User. string An ISO8601 formatted timestamp. Format: `date-time` string The type of Beacon Report. `first_party`: If this is the same individual as the one who submitted the KYC. `stolen`: If this is a different individual from the one who submitted the KYC. `synthetic`: If this is an individual using fabricated information. `account_takeover`: If this individual's account was compromised. `data_breach`: If this individual's data was compromised in a breach. `unknown`: If you aren't sure who committed the fraud. Possible values: `first_party`, `stolen`, `synthetic`, `account_takeover`, `data_breach`, `unknown` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, object The amount and currency of the fraud or attempted fraud. `fraud_amount` should be omitted to indicate an unknown fraud amount. string An ISO-4217 currency code. Possible values: `USD` number The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., `1.23`). Format: `double` object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating what caused a resource to be changed or updated. `dashboard` - The resource was created or updated by a member of your team via the Plaid dashboard. `api` - The resource was created or updated via the Plaid API. `system` - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be `system`. `bulk_import` - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be `bulk_import`. Possible values: `dashboard`, `api`, `system`, `bulk_import` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "becrpt_11111111111111", "beacon_user_id": "becusr_42cF1MNo42r9Xj", "created_at": "2020-07-24T03:26:02Z", "type": "first_party", "fraud_date": "1990-05-29", "event_date": "1990-05-29", "fraud_amount": { "iso_currency_code": "USD", "value": 100 }, "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /beacon/report/list  This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### List Beacon Reports for a Beacon User  Use the [/beacon/report/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportlist) endpoint to view all Beacon Reports you created for a specific Beacon User. The reports returned by this endpoint are exclusively reports you created for a specific user. A Beacon User can only have one active report at a time, but a new report can be created if a previous report has been deleted. The results from this endpoint are paginated; the `next_cursor` field will be populated if there is another page of results that can be retrieved. To fetch the next page, pass the `next_cursor` value as the `cursor` parameter in the next request. #### Request fields  required, string ID of the associated Beacon User. string An identifier that determines which page of results you receive. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```ruby client = create_client() request = Plaid::BeaconReportListRequest.new( { beacon_user_id: 'becusr_11111111111111' } ) response = client.beacon_report_list(request) ``` ```bash curl -X POST https://sandbox.plaid.com/beacon/report/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "beacon_user_id": "becusr_11111111111111" }' ``` ```node const request: BeaconReportListRequest = { beacon_user_id: 'becusr_11111111111111', }; try { const response = await plaidClient.beaconReportList(request); } catch (error) { // handle error } ``` ```java Client client = createClient(); BeaconReportListRequest request = new BeaconReportListRequest() .beaconUserId("becusr_11111111111111"); Response response = client.beaconReportList(request).execute(); ``` ```python client = create_client() request = BeaconReportListRequest( beacon_user_id='becusr_11111111111111' ) response = client.beacon_report_list(request) ``` ```go request := plaid.NewBeaconReportListRequest( "becusr_11111111111111" ) response, _, err := client.PlaidApi. BeaconReportList(ctx). BeaconReportListRequest(*request). Execute() ``` #### Response fields  \[object\] string ID of the associated Beacon Report. string ID of the associated Beacon User. string An ISO8601 formatted timestamp. Format: `date-time` string The type of Beacon Report. `first_party`: If this is the same individual as the one who submitted the KYC. `stolen`: If this is a different individual from the one who submitted the KYC. `synthetic`: If this is an individual using fabricated information. `account_takeover`: If this individual's account was compromised. `data_breach`: If this individual's data was compromised in a breach. `unknown`: If you aren't sure who committed the fraud. Possible values: `first_party`, `stolen`, `synthetic`, `account_takeover`, `data_breach`, `unknown` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, object The amount and currency of the fraud or attempted fraud. `fraud_amount` should be omitted to indicate an unknown fraud amount. string An ISO-4217 currency code. Possible values: `USD` number The amount value. This value can be 0 to indicate no money was lost. Must not contain more than two digits of precision (e.g., `1.23`). Format: `double` object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating what caused a resource to be changed or updated. `dashboard` - The resource was created or updated by a member of your team via the Plaid dashboard. `api` - The resource was created or updated via the Plaid API. `system` - The resource was created or updated automatically by a part of the Plaid Beacon system. For example, if another business using Plaid Beacon created a fraud report that matched one of your users, your matching user's status would automatically be updated and the audit trail source would be `system`. `bulk_import` - The resource was created or updated as part of a bulk import process. For example, if your company provided a CSV of user data as part of your initial onboarding, the audit trail source would be `bulk_import`. Possible values: `dashboard`, `api`, `system`, `bulk_import` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "beacon_reports": [ { "id": "becrpt_11111111111111", "beacon_user_id": "becusr_42cF1MNo42r9Xj", "created_at": "2020-07-24T03:26:02Z", "type": "first_party", "fraud_date": "1990-05-29", "event_date": "1990-05-29", "fraud_amount": { "iso_currency_code": "USD", "value": 100 }, "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /beacon/report\_syndication/get  This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### Get a Beacon Report Syndication  Returns a Beacon Report Syndication for a given Beacon Report Syndication id. #### Request fields  required, string ID of the associated Beacon Report Syndication. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```ruby client = create_client() request = Plaid::BeaconReportSyndicationGetRequest.new( { beacon_report_syndication_id: 'becrsn_11111111111111' } ) response = client.beacon_report_syndication_get(request) ``` ```bash curl -X POST https://sandbox.plaid.com/beacon/report_syndication/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "beacon_report_syndication_id": "becrsn_11111111111111" }' ``` ```node const request: BeaconReportSyndicationGetRequest = { beacon_report_syndication_id: 'becrsn_11111111111111', }; try { const response = await plaidClient.beaconReportSyndicationGet(request); } catch (error) { // handle error } ``` ```java BeaconReportSyndicationGetRequest request = new BeaconReportSyndicationGetRequest() .beaconReportSyndicationId("becrsn_11111111111111"); Response response = client.beaconReportSyndicationGet(request).execute(); ``` ```go request := plaid.NewBeaconReportSyndicationGetRequest("becrsn_11111111111111") response, _, err := client.PlaidApi. BeaconReportSyndicationGet(ctx). BeaconReportSyndicationGetRequest(*request). Execute() ``` ```python client = create_client() request = BeaconReportSyndicationGetRequest( beacon_report_syndication_id='becrsn_11111111111111' ) response = client.beacon_report_syndication_get(request) ``` #### Response fields  string ID of the associated Beacon Report Syndication. string ID of the associated Beacon User. object A subset of information from a Beacon Report that has been syndicated to a matching Beacon User in your program. The `id` field in the response is the ID of the original report that was syndicated. If the original report was created by your organization, the field will be filled with the ID of the report. Otherwise, the field will be `null` indicating that the original report was created by another Beacon customer. nullable, string ID of the associated Beacon Report. string An ISO8601 formatted timestamp. Format: `date-time` string The type of Beacon Report. `first_party`: If this is the same individual as the one who submitted the KYC. `stolen`: If this is a different individual from the one who submitted the KYC. `synthetic`: If this is an individual using fabricated information. `account_takeover`: If this individual's account was compromised. `data_breach`: If this individual's data was compromised in a breach. `unknown`: If you aren't sure who committed the fraud. Possible values: `first_party`, `stolen`, `synthetic`, `account_takeover`, `data_breach`, `unknown` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` object Analysis of which fields matched between the originally reported Beacon User and the Beacon User that the report was syndicated to. string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` \[object\] string The last 2-4 numeric characters of this account’s account number. string The routing number of the account. string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "becrsn_11111111111111", "beacon_user_id": "becusr_42cF1MNo42r9Xj", "report": { "id": "becrpt_11111111111111", "created_at": "2020-07-24T03:26:02Z", "type": "first_party", "fraud_date": "1990-05-29", "event_date": "1990-05-29" }, "analysis": { "address": "match", "date_of_birth": "match", "email_address": "match", "name": "match", "id_number": "match", "ip_address": "match", "phone_number": "match", "depository_accounts": [ { "account_mask": "4000", "routing_number": "021000021", "match_status": "match" } ] }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /beacon/report\_syndication/list  This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### List Beacon Report Syndications for a Beacon User  Use the [/beacon/report\_syndication/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationlist) endpoint to view all Beacon Reports that have been syndicated to a specific Beacon User. This endpoint returns Beacon Report Syndications which are references to Beacon Reports created either by you, or another Beacon customer, that matched the specified Beacon User. A Beacon User can have multiple active Beacon Report Syndications at once. The results from this endpoint are paginated; the `next_cursor` field will be populated if there is another page of results that can be retrieved. To fetch the next page, pass the `next_cursor` value as the `cursor` parameter in the next request. #### Request fields  required, string ID of the associated Beacon User. string An identifier that determines which page of results you receive. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```ruby client = create_client() request = Plaid::BeaconReportSyndicationListRequest.new( { beacon_user_id: 'becusr_11111111111111' } ) response = client.beacon_report_syndication_list(request) ``` ```bash curl -X POST https://sandbox.plaid.com/beacon/report_syndication/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "beacon_user_id": "becusr_11111111111111" }' ``` ```node const request: BeaconReportSyndicationListRequest = { beacon_user_id: 'becusr_11111111111111', }; try { const response = await plaidClient.beaconReportSyndicationList(request); } catch (error) { // handle error } ``` ```java BeaconReportSyndicationListRequest request = new BeaconReportSyndicationListRequest() .beaconUserId("becusr_11111111111111"); Response response = client.beaconReportSyndicationList(request).execute(); ``` ```go request := plaid.NewBeaconReportSyndicationListRequest( "becusr_11111111111111" ) response, _, err := client.PlaidApi. BeaconReportSyndicationList(ctx). BeaconReportSyndicationListRequest(*request). Execute() ``` ```python client = create_client() request = BeaconReportSyndicationListRequest( beacon_user_id='becusr_11111111111111' ) response = client.beacon_report_syndication_list(request) ``` #### Response fields  \[object\] string ID of the associated Beacon Report Syndication. string ID of the associated Beacon User. object A subset of information from a Beacon Report that has been syndicated to a matching Beacon User in your program. The `id` field in the response is the ID of the original report that was syndicated. If the original report was created by your organization, the field will be filled with the ID of the report. Otherwise, the field will be `null` indicating that the original report was created by another Beacon customer. nullable, string ID of the associated Beacon Report. string An ISO8601 formatted timestamp. Format: `date-time` string The type of Beacon Report. `first_party`: If this is the same individual as the one who submitted the KYC. `stolen`: If this is a different individual from the one who submitted the KYC. `synthetic`: If this is an individual using fabricated information. `account_takeover`: If this individual's account was compromised. `data_breach`: If this individual's data was compromised in a breach. `unknown`: If you aren't sure who committed the fraud. Possible values: `first_party`, `stolen`, `synthetic`, `account_takeover`, `data_breach`, `unknown` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` object Analysis of which fields matched between the originally reported Beacon User and the Beacon User that the report was syndicated to. string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` \[object\] string The last 2-4 numeric characters of this account’s account number. string The routing number of the account. string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "beacon_report_syndications": [ { "id": "becrsn_11111111111111", "beacon_user_id": "becusr_42cF1MNo42r9Xj", "report": { "id": "becrpt_11111111111111", "created_at": "2020-07-24T03:26:02Z", "type": "first_party", "fraud_date": "1990-05-29", "event_date": "1990-05-29" }, "analysis": { "address": "match", "date_of_birth": "match", "email_address": "match", "name": "match", "id_number": "match", "ip_address": "match", "phone_number": "match", "depository_accounts": [ { "account_mask": "4000", "routing_number": "021000021", "match_status": "match" } ] } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /beacon/duplicate/get  This feature is in currently in beta; Your account must be enabled for this feature in order to test it in Sandbox. To enable this feature or check your status, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### Get a Beacon Duplicate  Returns a Beacon Duplicate for a given Beacon Duplicate id. A Beacon Duplicate represents a pair of similar Beacon Users within your organization. Two Beacon User revisions are returned for each Duplicate record in either the `beacon_user1` or `beacon_user2` response fields. The `analysis` field in the response indicates which fields matched between `beacon_user1` and `beacon_user2`. #### Request fields  required, string ID of the associated Beacon Duplicate. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```ruby client = create_client() request = Plaid::BeaconDuplicateGetRequest.new( { beacon_duplicate_id: 'becdup_11111111111111' } ) response = client.beacon_duplicate_get(request) ``` ```bash curl -X POST https://sandbox.plaid.com/beacon/duplicate/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "beacon_duplicate_id": "becdup_11111111111111" }' ``` ```node const request: BeaconDuplicateGetRequest = { beacon_duplicate_id: 'becdup_11111111111111', }; try { const response = await plaidClient.beaconDuplicateGet(request); } catch (error) { // handle error } ``` ```java Client client = createClient(); BeaconDuplicateGetRequest request = new BeaconDuplicateGetRequest().beaconDuplicateId("becdup_11111111111111"); Response response = client.beaconDuplicateGet(request).execute(); ``` ```python client = create_client() request = BeaconDuplicateGetRequest(beacon_duplicate_id='becdup_11111111111111') response = client.beacon_duplicate_get(request) ``` ```go request := plaid.NewBeaconDuplicateGetRequest("becdup_11111111111111") response, _, err := client.PlaidApi. BeaconDuplicateGet(ctx). BeaconDuplicateGetRequest(*request). Execute() ``` #### Response fields  string ID of the associated Beacon Duplicate. object A Beacon User Revision identifies a Beacon User at some point in its revision history. string ID of the associated Beacon User. integer The `version` field begins with 1 and increments with each subsequent revision. object A Beacon User Revision identifies a Beacon User at some point in its revision history. string ID of the associated Beacon User. integer The `version` field begins with 1 and increments with each subsequent revision. object Analysis of which fields matched between one Beacon User and another. string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string An enum indicating the match type between two Beacon Users. `match` indicates that the provided input data was a strong match against the other Beacon User. `partial_match` indicates the data approximately matched the other Beacon User. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to compare this field against the other Beacon User and it did not match the provided input data. `no_data` indicates that Plaid was unable to compare this field against the original Beacon User because the field was not present in one of the Beacon Users. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "becdup_11111111111111", "beacon_user1": { "id": "becusr_42cF1MNo42r9Xj", "version": 1 }, "beacon_user2": { "id": "becusr_42cF1MNo42r9Xj", "version": 1 }, "analysis": { "address": "match", "date_of_birth": "match", "email_address": "match", "name": "match", "id_number": "match", "ip_address": "match", "phone_number": "match" }, "request_id": "saKrIBuEB9qJZng" } ``` ### Webhooks  A user in `cleared` status may change to a `pending_review` status after a Beacon Report Syndication is received, which would trigger both a `USER_STATUS_UPDATED` as well as a `REPORT_SYNDICATION_CREATED` webhook. New Beacon Users may also be flagged as duplicates of another user, which triggers a `DUPLICATE_DETECTED` webhook. Beacon Reports created and managed by your account will trigger `REPORT_CREATED` and `REPORT_UPDATED` webhooks, and may also result in a `USER_STATUS_UPDATED` if the user status is changed from `cleared` to `rejected` at that time. \=\*=\*=\*= #### USER\_STATUS\_UPDATED  Fired when a Beacon User status has changed, which can occur manually via the dashboard or when information is reported to the Beacon network. #### Properties  string `BEACON` string `USER_STATUS_UPDATED` string The ID of the associated Beacon user. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "BEACON", "webhook_code": "USER_STATUS_UPDATED", "beacon_user_id": "becusr_4WciCrtbxF76T8", "environment": "production" } ``` \=\*=\*=\*= #### REPORT\_CREATED  Fired when one of your Beacon Users is first reported to the Beacon network. #### Properties  string `BEACON` string `REPORT_CREATED` string The ID of the associated Beacon Report. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "BEACON", "webhook_code": "REPORT_CREATED", "beacon_report_id": "becrpt_2zugxV6hWQZG91", "environment": "production" } ``` \=\*=\*=\*= #### REPORT\_UPDATED  Fired when one of your existing Beacon Reports has been modified or removed from the Beacon Network. #### Properties  string `BEACON` string `REPORT_UPDATED` string The ID of the associated Beacon Report. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "BEACON", "webhook_code": "REPORT_UPDATED", "beacon_report_id": "becrpt_2zugxV6hWQZG91", "environment": "production" } ``` \=\*=\*=\*= #### REPORT\_SYNDICATION\_CREATED  Fired when a report created on the Beacon Network matches with one of your Beacon Users. #### Properties  string `BEACON` string `REPORT_SYNDICATION_CREATED` string The ID of the associated Beacon Report Syndication. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "BEACON", "webhook_code": "REPORT_SYNDICATION_CREATED", "beacon_report_syndication_id": "becrsn_eZPgiiv3JH8rfT", "environment": "production" } ``` \=\*=\*=\*= #### DUPLICATE\_DETECTED  Fired when a Beacon User created within your organization matches one of your existing users. #### Properties  string `BEACON` string `DUPLICATE_DETECTED` string The ID of the associated Beacon Duplicate. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "BEACON", "webhook_code": "DUPLICATE_DETECTED", "beacon_duplicate_id": "becdup_erJcFn97r9sugZ", "environment": "production" } ``` --- # API - Consumer Report (by Plaid Check) | Plaid Docs Plaid Check  ============ #### API reference for Plaid Check endpoints and webhooks  | Endpoints | | | --- | --- | | [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) | Retrieve the base Consumer Report for your user | | [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) | Retrieve cash flow insights from your user's banks | | [/cra/check\_report/network\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportnetwork_insightsget) | Retrieve connection insights from the Plaid network (beta) | | [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) | Retrieve cash flow insights from our partners | | [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) | Retrieve Consumer Reports in PDF format | | [/cra/check\_report/cashflow\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcashflow_insightsget) | Retrieve Cash Flow Insights report | | [/cra/check\_report/lend\_score/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportlend_scoreget) | Retrieve a Plaid LendScore generated from your user's banking data | | [/cra/check\_report/verification/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationget) | Retrieve Verification Reports (Home Lending Report, Employment Refresh) for your user | | [/cra/check\_report/verification/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationpdfget) | Retrieve Verification Reports in PDF format | | [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) | Generate a new Consumer Report for your user with the latest data | | [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) | Get Cash Flow Updates (beta) | | [/cra/monitoring\_insights/subscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightssubscribe) | Subscribe to Cash Flow Updates (beta) | | [/cra/monitoring\_insights/unsubscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsunsubscribe) | Unsubscribe from Cash Flow Updates (beta) | | See also | | | --- | --- | | [Migrate to new User APIs](https://plaid.com/docs/api/users/migrate-to-new-user-apis/index.html.md) | Migration guide for existing Consumer Report integrations on legacy User APIs | | [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) | Create a token for initializing a Link session with Plaid Check | | [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) | Create a user ID and token for use with Plaid Check | | [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) | Update an existing user token to work with Plaid Check, or change user details | | [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) | Removes the user and their relevant data | | [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) | Returns Items associated with a user along with their corresponding statuses | | [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) | Manually trigger a cashflow insights update for a user (Sandbox only) | | Webhooks | | | --- | --- | | [USER\_CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_ready) | A Consumer Report is ready to be retrieved | | [USER\_CHECK\_REPORT\_FAILED](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_failed) | Plaid Check failed to create a report | | [CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#check_report_ready) | A Consumer Report is ready to be retrieved (legacy) | | [CHECK\_REPORT\_FAILED](https://plaid.com/docs/api/products/check/index.html.md#check_report_failed) | Plaid Check failed to create a report (legacy) | | Cash Flow Updates (beta) webhooks | | | --- | --- | | [CASH\_FLOW\_INSIGHTS\_UPDATED](https://plaid.com/docs/api/products/check/index.html.md#insights_updated) | Insights have been refreshed | | [INSIGHTS\_UPDATED](https://plaid.com/docs/api/products/check/index.html.md#insights_updated) | Insights have been refreshed (legacy) | | [LARGE\_DEPOSIT\_DETECTED](https://plaid.com/docs/api/products/check/index.html.md#large_deposit_detected) | A large deposit over $5000 has been detected (legacy) | | [LOW\_BALANCE\_DETECTED](https://plaid.com/docs/api/products/check/index.html.md#low_balance_detected) | Current balance has crossed below $100 (legacy) | | [NEW\_LOAN\_PAYMENT\_DETECTED](https://plaid.com/docs/api/products/check/index.html.md#new_loan_payment_detected) | A new loan payment has been detected (legacy) | | [NSF\_OVERDRAFT\_DETECTED](https://plaid.com/docs/api/products/check/index.html.md#nsf_overdraft_detected) | An overdraft transaction has been detected (legacy) | \=\*=\*=\*= #### /cra/check\_report/base\_report/get  #### Retrieve a Base Report  This endpoint allows you to retrieve the Base Report for your user, allowing you to receive comprehensive bank account and cash flow data. You should call this endpoint after you've received a `CHECK_REPORT_READY` or a `USER_CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If the most recent consumer report for the user doesn't have sufficient data to generate the base report, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/base_report/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw" }' ``` ```node try { const response = await client.craCheckReportBaseReportGet({ user_id: 'usr_9nSp2KuZ2x4JDw', }); } catch (error) { // handle error } ``` ```python request = CraCheckReportBaseReportGetRequest( user_id='usr_9nSp2KuZ2x4JDw' ) response = client.cra_check_report_base_report_get(request) ``` ```ruby request = Plaid::CraCheckReportBaseReportGetRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw' } ) response = client.cra_check_report_base_report_get(request) ``` ```java CraCheckReportBaseReportGetRequest request = new CraCheckReportBaseReportGetRequest() .userId("usr_9nSp2KuZ2x4JDw"); Response response = client .craCheckReportBaseReportGet(request) .execute(); ``` ```go request := plaid.NewCraCheckReportBaseReportGetRequest(); request.SetUserId("usr_9nSp2KuZ2x4JDw"); response, _, err := client.PlaidApi. CraCheckReportBaseReportGet(ctx). CraCheckReportBaseReportGetRequest(*request). Execute() ``` #### Response fields  object An object representing a Base Report string A unique ID identifying an Base Report. Like all Plaid identifiers, this ID is case sensitive. string The date and time when the Base Report was created, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (e.g. "2018-04-12T03:32:11Z"). Format: `date-time` number The number of days of transaction history requested. nullable, string Client-generated identifier, which can be used by lenders to track loan applications. \[object\] Data returned by Plaid about each of the Items included in the Base Report. string The full financial institution name associated with the Item. string The id of the financial institution associated with the Item. string The date and time when this Item’s data was last retrieved from the financial institution, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` string The `item_id` of the Item associated with this webhook, warning, or error \[object\] Data about each of the accounts open on the Item. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the `account_id` is case sensitive. object Information about an account's balances. nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get`; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the oldest acceptable balance when making a request to `/accounts/balance/get`. This field is only used and expected when the institution is `ins_128026` (Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an `INVALID_REQUEST` error with the code of `INVALID_FIELD` will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See [account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of account types. If the balance that is pulled is older than the given timestamp for Items with this field required, an `INVALID_REQUEST` error with the code of `LAST_UPDATED_DATETIME_OUT_OF_RANGE` will be returned with the most recent timestamp for the requested account contained in the response. Format: `date-time` nullable, number The average historical balance for the entire report Format: `double` \[object\] The average historical balance of each calendar month string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). object This contains an amount, denominated in the currency specified by either `iso_currency_code` or `unofficial_currency_code` number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, number The average historical balance from the most recent 30 days Format: `double` \[object\] The information about previously submitted valid dispute statements by the consumer deprecated, string (Deprecated) A unique identifier (UUID) of the consumer dispute that can be used for troubleshooting string Date of the disputed field (e.g. transaction date), in an ISO 8601 format (YYYY-MM-DD) Format: `date` string Type of data being disputed by the consumer Possible values: `TRANSACTION`, `BALANCE`, `IDENTITY`, `OTHER` string Text content of dispute nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user. object Metadata about the extracted account. nullable, string The beginning of the range of the financial institution provided data for the account, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). Format: `date` nullable, string The end of the range of the financial institution provided data for the account, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). Format: `date` string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` number The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account. \[object\] Transaction history associated with the account. Transaction history returned by endpoints such as `/transactions/get` or `/investments/transactions/get` will be returned in the top-level `transactions` field instead. Some transactions may have their details masked in accordance to the FCRA. These will appear with a `credit_category` of `MASKED_TRANSACTION_CATEGORY`. string The ID of the account in which this transaction occurred. number The settled value of the transaction, denominated in the transaction's currency, as stated in `iso_currency_code` or `unofficial_currency_code`. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. Format: `double` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string The string returned by the financial institution to describe the transaction. nullable, object Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. See the [taxonomy csv file](https://plaid.com/documents/credit-category-taxonomy.csv) for a full list of credit categories. string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string The check number of the transaction. This field is only populated for check transactions. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). Format: `date` nullable, string The date on which the transaction took place, in IS0 8601 format. object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. nullable, string The merchant name, as enriched by Plaid from the `name` field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be `null`. boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. nullable, string The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. \[object\] Data returned by the financial institution about the account owner or owners. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same `owner` object, not in multiple owner objects within the array. This array can also be empty if no owners are found. \[string\] A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's `names` array. \[object\] A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The phone number. boolean When `true`, identifies the phone number as the primary number on an account. string The type of phone number. Possible values: `home`, `work`, `office`, `mobile`, `mobile1`, `other` \[object\] A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The email address. boolean When `true`, identifies the email address as the primary email on an account. string The type of email account as described by the financial institution. Possible values: `primary`, `secondary`, `other` \[object\] Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. object Data about the components comprising an address. nullable, string The full city name nullable, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code boolean When `true`, identifies the address as the primary address on an account. nullable, string How an asset is owned. `association`: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. `individual`: Ownership by an individual. `joint`: Joint ownership by multiple parties. `trust`: Ownership by a revocable or irrevocable trust. Possible values: `null`, `individual`, `joint`, `association`, `trust` deprecated, object Calculated insights derived from transaction-level data. This field has been deprecated in favor of [Base Report attributes aggregated across accounts](https://plaid.com/docs/api/products/check/index.html.md#cra-check_report-base_report-get-response-report-attributes) and will be removed in a future release. nullable, string Date of the earliest transaction for the account. Format: `date` nullable, string Date of the most recent transaction for the account. Format: `date` integer Number of days days available for the account. number Average number of days between sequential transactions \[object\] Longest gap between sequential transactions in a time period. This array can include multiple time periods. string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` nullable, integer Largest number of days between sequential transactions for this time period. \[object\] The number of debits into the account. This array will be empty for non-depository accounts. string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` integer The number of credits or debits out of the account for this time period. \[object\] Average amount of debit transactions into the account in a time period. This array will be empty for non-depository accounts. This field only takes into account USD transactions from the account. string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` object This contains an amount, denominated in the currency specified by either `iso_currency_code` or `unofficial_currency_code` number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. \[object\] The number of outflows from the account. This array will be empty for non-depository accounts. string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` integer The number of credits or debits out of the account for this time period. \[object\] Average amount of transactions out of the account in a time period. This array will be empty for non-depository accounts. This field only takes into account USD transactions from the account. string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` object This contains an amount, denominated in the currency specified by either `iso_currency_code` or `unofficial_currency_code` number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. integer Number of days with no transactions object Calculated attributes derived from transaction-level data. nullable, boolean Prediction indicator of whether the account is a primary account. Only one account per account type across the items connected will have a value of true. nullable, number Value ranging from 0-1. The higher the score, the more confident we are of the account being the primary account. integer The number of net NSF fee transactions for a given account within the report time range (not counting any fees that were reversed within the time range). integer The number of net NSF fee transactions within the last 30 days for a given account (not counting any fees that were reversed within the time range). integer The number of net NSF fee transactions within the last 60 days for a given account (not counting any fees that were reversed within the time range). integer The number of net NSF fee transactions within the last 90 days for a given account (not counting any fees that were reversed within the time range). nullable, object Total amount of debit transactions into the account in the time period of the report. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of debit transactions into the account in the last 30 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of debit transactions into the account in the last 60 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of debit transactions into the account in the last 90 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the account in the time period of the report. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the account in the last 30 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the account in the last 60 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the account in the last 90 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. object Calculated attributes derived from transaction-level data, aggregated across accounts. integer The number of net NSF fee transactions in the time range for the report (not counting any fees that were reversed within that time range). integer The number of net NSF fee transactions in the last 30 days in the report (not counting any fees that were reversed within that time range). integer The number of net NSF fee transactions in the last 60 days in the report (not counting any fees that were reversed within that time range). integer The number of net NSF fee transactions in the last 90 days in the report (not counting any fees that were reversed within that time range). nullable, object Total amount of debit transactions into the report's accounts in the time period of the report. This field only takes into account USD transactions from the accounts. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of debit transactions into the report's accounts in the last 30 days. This field only takes into account USD transactions from the accounts. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of debit transactions into the report's accounts in the last 60 days. This field only takes into account USD transactions from the accounts. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of debit transactions into the report's account in the last 90 days. This field only takes into account USD transactions from the accounts. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the report's accounts in the time period of the report. This field only takes into account USD transactions from the accounts. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the report's accounts in the last 30 days. This field only takes into account USD transactions from the accounts. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the report's accounts in the last 60 days. This field only takes into account USD transactions from the accounts. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the report's accounts in the last 90 days. This field only takes into account USD transactions from the accounts. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. \[object\] This array contains any information about errors or alerts related to the Base Report that did not block generation of the report. string The warning type, which will always be `BASE_REPORT_WARNING` string The warning code identifies a specific kind of warning. `IDENTITY_UNAVAILABLE`: Account-owner information is not available. `TRANSACTIONS_UNAVAILABLE`: Transactions information associated with Credit and Depository accounts are unavailable. `USER_FRAUD_ALERT`: The User has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Note: when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: `IDENTITY_UNAVAILABLE`, `TRANSACTIONS_UNAVAILABLE`, `USER_FRAUD_ALERT` nullable, object An error object and associated `item_id` used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The `item_id` of the Item associated with this webhook, warning, or error string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "report": { "date_generated": "2024-07-16T01:52:42.912331716Z", "days_requested": 365, "attributes": { "total_inflow_amount": { "amount": -2500, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_inflow_amount_30d": { "amount": -1000, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_inflow_amount_60d": { "amount": -2500, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_inflow_amount_90d": { "amount": -2500, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_outflow_amount": { "amount": 2500, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_outflow_amount_30d": { "amount": 1000, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_outflow_amount_60d": { "amount": 2500, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_outflow_amount_90d": { "amount": 2500, "iso_currency_code": "USD", "unofficial_currency_code": null } }, "items": [ { "accounts": [ { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_insights": { "average_days_between_transactions": 0.15, "average_inflow_amount": [ { "end_date": "2024-07-31", "start_date": "2024-07-01", "total_amount": { "amount": 1077.93, "iso_currency_code": "USD", "unofficial_currency_code": null } } ], "average_inflow_amounts": [ { "end_date": "2024-07-31", "start_date": "2024-07-01", "total_amount": { "amount": 1077.93, "iso_currency_code": "USD", "unofficial_currency_code": null } }, { "end_date": "2024-08-31", "start_date": "2024-08-01", "total_amount": { "amount": 1076.93, "iso_currency_code": "USD", "unofficial_currency_code": null } } ], "average_outflow_amount": [ { "end_date": "2024-07-31", "start_date": "2024-07-01", "total_amount": { "amount": 34.95, "iso_currency_code": "USD", "unofficial_currency_code": null } } ], "average_outflow_amounts": [ { "end_date": "2024-07-31", "start_date": "2024-07-01", "total_amount": { "amount": 34.95, "iso_currency_code": "USD", "unofficial_currency_code": null } }, { "end_date": "2024-08-31", "start_date": "2024-08-01", "total_amount": { "amount": 0, "iso_currency_code": "USD", "unofficial_currency_code": null } } ], "days_available": 365, "longest_gap_between_transactions": [ { "days": 1, "end_date": "2024-07-31", "start_date": "2024-07-01" } ], "longest_gaps_between_transactions": [ { "days": 1, "end_date": "2024-07-31", "start_date": "2024-07-01" }, { "days": 2, "end_date": "2024-08-31", "start_date": "2024-08-01" } ], "most_recent_transaction_date": "2024-07-16", "number_of_days_no_transactions": 0, "number_of_inflows": [ { "count": 1, "end_date": "2024-07-31", "start_date": "2024-07-01" } ], "number_of_outflows": [ { "count": 27, "end_date": "2024-07-31", "start_date": "2024-07-01" } ], "oldest_transaction_date": "2024-07-12" }, "balances": { "available": 5000, "average_balance": 4956.12, "average_monthly_balances": [ { "average_balance": { "amount": 4956.12, "iso_currency_code": "USD", "unofficial_currency_code": null }, "end_date": "2024-07-31", "start_date": "2024-07-01" } ], "current": 5000, "iso_currency_code": "USD", "limit": null, "most_recent_thirty_day_average_balance": 4956.125, "unofficial_currency_code": null }, "consumer_disputes": [], "days_available": 365, "mask": "1208", "metadata": { "start_date": "2024-01-01", "end_date": "2024-07-16" }, "name": "Checking", "official_name": "Plaid checking", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "postal_code": "93405-2255", "region": "CA", "street": "2493 Leisure Lane" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholder1@example.com", "primary": false, "type": "secondary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "+1 111-555-3333", "primary": false, "type": "home" }, { "data": "+1 111-555-4444", "primary": false, "type": "work" }, { "data": "+1 111-555-5555", "primary": false, "type": "mobile" } ] } ], "ownership_type": null, "subtype": "checking", "transactions": [ { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 37.07, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-12", "date_posted": "2024-07-12T00:00:00Z", "date_transacted": "2024-07-12", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Amazon", "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM", "pending": false, "transaction_id": "XA7ZLy8rXzt7D3j9B6LMIgv5VxyQkAhbKjzmp", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 51.61, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-12", "date_posted": "2024-07-12T00:00:00Z", "date_transacted": "2024-07-12", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Domino's", "original_description": "DOMINO's XXXX 111-222-3333", "pending": false, "transaction_id": "VEPeMbWqRluPVZLQX4MDUkKRw41Ljzf9gyLBW", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 7.55, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_FURNITURE_AND_HARDWARE", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-12", "date_posted": "2024-07-12T00:00:00Z", "date_transacted": "2024-07-12", "iso_currency_code": "USD", "location": { "address": null, "city": "Chicago", "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "IKEA", "original_description": "IKEA CHICAGO", "pending": false, "transaction_id": "6GQZARgvroCAE1eW5wpQT7w3oB6nvzi8DKMBa", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 12.87, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_SPORTING_GOODS", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-12", "date_posted": "2024-07-12T00:00:00Z", "date_transacted": "2024-07-12", "iso_currency_code": "USD", "location": { "address": null, "city": "Redlands", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "CA", "state": "CA", "store_number": null, "zip": null }, "merchant_name": "Nike", "original_description": "NIKE REDLANDS CA", "pending": false, "transaction_id": "DkbmlP8BZxibzADqNplKTeL8aZJVQ1c3WR95z", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 44.21, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-12", "date_posted": "2024-07-12T00:00:00Z", "date_transacted": "2024-07-12", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": null, "original_description": "POKE BROS * POKE BRO IL", "pending": false, "transaction_id": "RpdN7W8GmRSdjZB9Jm7ATj4M86vdnktapkrgL", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 36.82, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_DISCOUNT_STORES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-13", "date_posted": "2024-07-13T00:00:00Z", "date_transacted": "2024-07-13", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Family Dollar", "original_description": "FAMILY DOLLAR", "pending": false, "transaction_id": "5AeQWvo5KLtAD9wNL68PTdAgPE7VNWf5Kye1G", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 13.27, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-13", "date_posted": "2024-07-13T00:00:00Z", "date_transacted": "2024-07-13", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Instacart", "original_description": "INSTACART HTTPSINSTACAR CA", "pending": false, "transaction_id": "Jjlr3MEVg1HlKbdkZj39ij5a7eg9MqtB6MWDo", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 36.03, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-13", "date_posted": "2024-07-13T00:00:00Z", "date_transacted": "2024-07-13", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": null, "original_description": "POKE BROS * POKE BRO IL", "pending": false, "transaction_id": "kN9KV7yAZJUMPn93KDXqsG9MrpjlyLUL6Dgl8", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 54.74, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-13", "date_posted": "2024-07-13T00:00:00Z", "date_transacted": "2024-07-13", "iso_currency_code": "USD", "location": { "address": null, "city": "Whittier", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "CA", "state": "CA", "store_number": null, "zip": null }, "merchant_name": "Smart & Final", "original_description": "POS SMART AND FINAL 111 WHITTIER CA", "pending": false, "transaction_id": "lPvrweZAMqHDar43vwWKs547kLZVEzfpogGVJ", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 37.5, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-13", "date_posted": "2024-07-13T00:00:00Z", "date_transacted": "2024-07-13", "iso_currency_code": "USD", "location": { "address": "1627 N 24th St", "city": "Phoenix", "country": null, "lat": null, "lon": null, "postal_code": "85008", "region": "AZ", "state": "AZ", "store_number": null, "zip": "85008" }, "merchant_name": "Taqueria El Guerrerense", "original_description": "TAQUERIA EL GUERRERO PHOENIX AZ", "pending": false, "transaction_id": "wka74WKqngiyJ3pj7dl5SbpLGQBZqyCPZRDbP", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 41.42, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Amazon", "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM", "pending": false, "transaction_id": "BBGnV4RkerHjn8WVavGyiJbQ95VNDaC4M56bJ", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": -1077.93, "check_number": null, "credit_category": { "detailed": "INCOME_OTHER", "primary": "INCOME" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Lyft", "original_description": "LYFT TRANSFER", "pending": false, "transaction_id": "3Ej78yKJlQu1Abw7xzo4U4JR6pmwzntZlbKDK", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 47.17, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": "Whittier", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "CA", "state": "CA", "store_number": null, "zip": null }, "merchant_name": "Smart & Final", "original_description": "POS SMART AND FINAL 111 WHITTIER CA", "pending": false, "transaction_id": "rMzaBpJw8jSZRJQBabKdteQBwd5EaWc7J9qem", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 12.37, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": "Whittier", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "CA", "state": "CA", "store_number": null, "zip": null }, "merchant_name": "Smart & Final", "original_description": "POS SMART AND FINAL 111 WHITTIER CA", "pending": false, "transaction_id": "zWPZjkmzynTyel89ZjExS59DV6WAaZflNBJ56", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 44.18, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": "Portland", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "OR", "state": "OR", "store_number": "1111", "zip": null }, "merchant_name": "Safeway", "original_description": "SAFEWAY #1111 PORTLAND OR 111111", "pending": false, "transaction_id": "K7qzx1nP8ptqgwaRMbxyI86XrqADMluRpkWx5", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 45.37, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Uber Eats", "original_description": "UBER EATS", "pending": false, "transaction_id": "qZrdzLRAgNHo5peMdD9xIzELl3a1NvcgrPAzL", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 15.22, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Amazon", "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM", "pending": false, "transaction_id": "NZzx4oRPkAHzyRekpG4PTZkWnBPqEyiy6pB1M", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 26.33, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Domino's", "original_description": "DOMINO's XXXX 111-222-3333", "pending": false, "transaction_id": "x84eNArKbESz8Woden6LT3nvyogeJXc64Pp35", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 39.8, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_DISCOUNT_STORES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Family Dollar", "original_description": "FAMILY DOLLAR", "pending": false, "transaction_id": "dzWnyxwZ4GHlZPGgrNyxiMG7qd5jDgCJEz5jL", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 45.06, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Instacart", "original_description": "INSTACART HTTPSINSTACAR CA", "pending": false, "transaction_id": "4W7eE9rZqMToDArbPeLNIREoKpdgBMcJbVNQD", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 34.91, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": "Whittier", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "CA", "state": "CA", "store_number": null, "zip": null }, "merchant_name": "Smart & Final", "original_description": "POS SMART AND FINAL 111 WHITTIER CA", "pending": false, "transaction_id": "j4yqDjb7QwS7woGzqrgDIEG1NaQVZwf6Wmz3D", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 49.78, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": "Portland", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "OR", "state": "OR", "store_number": "1111", "zip": null }, "merchant_name": "Safeway", "original_description": "SAFEWAY #1111 PORTLAND OR 111111", "pending": false, "transaction_id": "aqgWnze7xoHd6DQwLPnzT5dgPKjB1NfZ5JlBy", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 54.24, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": "Portland", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "OR", "state": "OR", "store_number": "1111", "zip": null }, "merchant_name": "Safeway", "original_description": "SAFEWAY #1111 PORTLAND OR 111111", "pending": false, "transaction_id": "P13aP8b7nmS3WQoxg1PMsdvMK679RNfo65B4G", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 41.79, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-16", "date_posted": "2024-07-16T00:00:00Z", "date_transacted": "2024-07-16", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Amazon", "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM", "pending": false, "transaction_id": "7nZMG6pXz8SADylMqzx7TraE4qjJm7udJyAGm", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 33.86, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-16", "date_posted": "2024-07-16T00:00:00Z", "date_transacted": "2024-07-16", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Instacart", "original_description": "INSTACART HTTPSINSTACAR CA", "pending": false, "transaction_id": "MQr3ap7PWEIrQG7bLdaNsxyBV7g1KqCL6pwoy", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 27.08, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-16", "date_posted": "2024-07-16T00:00:00Z", "date_transacted": "2024-07-16", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": null, "original_description": "POKE BROS * POKE BRO IL", "pending": false, "transaction_id": "eBAk9dvwNbHPZpr8W69dU3rekJz47Kcr9BRwl", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 25.94, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_FURNITURE_AND_HARDWARE", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-16", "date_posted": "2024-07-16T00:00:00Z", "date_transacted": "2024-07-16", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "The Home Depot", "original_description": "THE HOME DEPOT", "pending": false, "transaction_id": "QLx4jEJZb9SxRm7aWbjAio3LrgZ5vPswm64dE", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 27.57, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_OTHER_GENERAL_MERCHANDISE", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-16", "date_posted": "2024-07-16T00:00:00Z", "date_transacted": "2024-07-16", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": null, "original_description": "The Press Club", "pending": false, "transaction_id": "ZnQ1ovqBldSQ6GzRbroAHLdQP68BrKceqmAjX", "unofficial_currency_code": null } ], "type": "depository" } ], "date_last_updated": "2024-07-16T01:52:42.912331716Z", "institution_id": "ins_109512", "institution_name": "Houndstooth Bank", "item_id": "NZzx4oRPkAHzyRekpG4PTZkDNkQW93tWnyGeA" } ], "report_id": "f3bb434f-1c9b-4ef2-b76c-3d1fd08156ec" }, "warnings": [], "request_id": "FibfL8t3s71KJnj" } ``` \=\*=\*=\*= #### /cra/check\_report/income\_insights/get  #### Retrieve cash flow information from your user's banks  This endpoint allows you to retrieve the Income Insights report for your user. You should call this endpoint after you’ve received a `CHECK_REPORT_READY` or a `USER_CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If the most recent consumer report for the user doesn’t have sufficient data to generate the base report, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . NOTE: The following schema was updated in April 2026 to reflect the response when the provided version is "II2". Please see [this document](https://docs.google.com/document/d/1kQkQ7FOgFaC4n-sUGUk74hoXZNY_L_nJeCuMe7Keip4/edit?tab=t.0#heading=h.rudamzinus2i) for guidance on migrating to II2 if you are currently using the II1 version, and [this section](https://docs.google.com/document/d/1kQkQ7FOgFaC4n-sUGUk74hoXZNY_L_nJeCuMe7Keip4/edit?tab=t.0#bookmark=id.tdcc2wpk0h60) for an example II1 response along with its [documentation](https://docs.google.com/document/d/1kQkQ7FOgFaC4n-sUGUk74hoXZNY_L_nJeCuMe7Keip4/edit?tab=t.36c85n2ircqk#heading=h.79dwr5c1iszl) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . object Defines configuration options to generate Income Insights. object Filters the returned income streams based on the specified income categories. If no filters are requested, streams from the following default set of categories are returned: * `EARNED_INCOME.*` (`EARNED_INCOME.SALARY`, `EARNED_INCOME.GIG_ECONOMY`, `EARNED_INCOME.SELF_EMPLOYED`) * `BENEFITS.DISABILITY` * `RETIREMENT.*` (`RETIREMENT.GOVERNMENT_DERIVED`, `RETIREMENT.PRIVATE_RETIREMENT`, `RETIREMENT.PLAN_DISTRIBUTION`) The final list of income categories is generated by adding the `included_categories`, then removing the `excluded_categories`. Priority is given to `excluded_categories` in the case of collisions. Filter patterns supported: * `*`: All categories * `PRIMARY.*`: All categories within the specified primary category * `PRIMARY.SECONDARY`: A specific income category For a list of income categories, see the [Income V2 Category Taxonomy](https://plaid.com/documents/income-v2-category-taxonomy.csv) . required, \[string\] Includes income streams matching the specified categories. \[string\] Excludes income streams matching the specified categories. required, string The version of Income Insights to use. Possible values: `II2` ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/income_insights/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw" }' ``` ```node try { const response = await client.craCheckReportIncomeInsightsGet({ user_id: 'usr_9nSp2KuZ2x4JDw', }); } catch (error) { // handle error } ``` ```python request = CraCheckReportIncomeInsightsGetRequest( user_id='usr_9nSp2KuZ2x4JDw' ) response = client.cra_check_report_income_insights_get(request) ``` ```ruby request = Plaid::CraCheckReportIncomeInsightsGetRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw' } ) response = client.cra_check_report_income_insights_get(request) ``` ```java CraCheckReportIncomeInsightsGetRequest request = new CraCheckReportIncomeInsightsGetRequest() .userId("usr_9nSp2KuZ2x4JDw"); Response response = client .craCheckReportIncomeInsightsGet(request) .execute(); ``` ```go request := plaid.NewCraCheckReportIncomeInsightsGetRequest(); request.SetUserId("usr_9nSp2KuZ2x4JDw"); response, _, err := client.PlaidApi. CraCheckReportIncomeInsightsGet(ctx). CraCheckReportIncomeInsightsGetRequest(*request). Execute() ``` #### Response fields  object The Check Income Insights Report for an end user. string The unique identifier associated with the Check Income Insights Report. string The time when the Check Income Insights Report was generated. Format: `date-time` integer The number of days requested by the customer for the Check Income Insights Report. nullable, string Client-generated identifier, which can be used by lenders to track loan applications. \[object\] The list of Items in the report along with the associated metadata about the Item. string The `item_id` of the Item associated with this webhook, warning, or error \[object\] The Item's accounts that have bank income data. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the `account_id` is case sensitive. nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user. object An object containing metadata about the extracted account. nullable, string The date of the earliest extracted transaction, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). Format: `date` nullable, string The date of the most recent extracted transaction, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). Format: `date` string The name of the bank account. nullable, string The official name of the bank account. string Valid account subtypes for depository accounts. For a list containing descriptions of each subtype, see [Account schemas](https://plaid.com/docs/api/accounts/index.html.md#StandaloneAccountType-depository) . Possible values: `checking`, `savings`, `hsa`, `cd`, `money market`, `paypal`, `prepaid`, `cash management`, `ebt`, `limited purpose checking`, `all` string The account type. This will always be `depository`. Possible values: `depository` string The time when this Item's data was last retrieved from the financial institution. Format: `date-time` string The unique identifier of the institution associated with the Item. string The name of the institution associated with the Item. nullable, object Aggregated summary of all income streams for this user. \[object\] List of a user's aggregated income metrics for each currency. nullable, object Modeled estimate of current income based on recently observed income transactions. object Modeled estimate of the monthly income. number Gross Income modeled from trends of observed transactions. number Net Income estimated from observed transactions. object Modeled estimate of the annual income. number Gross Income modeled from trends of observed transactions. number Net Income estimated from observed transactions. nullable, object Forward-looking modeled estimate of income based on recent income transactions and trends in active streams. object Modeled estimate of the monthly income. number Gross Income modeled from trends of observed transactions. number Net Income estimated from observed transactions. object Modeled estimate of the annual income. number Gross Income modeled from trends of observed transactions. number Net Income estimated from observed transactions. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. \[object\] The list of income streams for this user. string A unique identifier for an income stream. If the report is regenerated and a new `report_id` is created, the new report will have a new set of `income_stream_id`s. string Minimum of all dates within the specific income stream for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string Maximum of all dates within the specific income stream for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The most common name or original description for the underlying income transactions. object Modeled insights for a given income stream. object The income category for a given stream. The streams returned in the response will be filtered based on these primary and secondary income categories. See the [Income V2 Category Taxonomy](https://plaid.com/documents/income-v2-category-taxonomy.csv) for a full list of income categories. string A high level category that communicates the broad category of the stream. string A granular category conveying the stream's intent. string The income pay frequency. Possible values: `WEEKLY`, `BIWEEKLY`, `SEMI_MONTHLY`, `MONTHLY`, `DAILY`, `UNKNOWN` nullable, object The object containing data about the income provider. string The name of the income provider. boolean Indicates whether the income provider name is normalized by comparing it against a canonical set of known providers. string The status of the income sources. `ACTIVE`: The income source is active. `INACTIVE`: The income source is inactive. `UNKNOWN`: The income source status is unknown. Possible values: `ACTIVE`, `INACTIVE`, `UNKNOWN` nullable, object Metadata of the income stream's next payment. string The expected date of the income stream's next payment. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` object Modeled income metrics for a given income stream or user summary. nullable, object Modeled estimate of current income based on recently observed income transactions. object Modeled estimate of the monthly income. number Gross Income modeled from trends of observed transactions. number Net Income estimated from observed transactions. object Modeled estimate of the annual income. number Gross Income modeled from trends of observed transactions. number Net Income estimated from observed transactions. nullable, object Forward-looking modeled estimate of income based on recent income transactions and trends in active streams. object Modeled estimate of the monthly income. number Gross Income modeled from trends of observed transactions. number Net Income estimated from observed transactions. object Modeled estimate of the annual income. number Gross Income modeled from trends of observed transactions. number Net Income estimated from observed transactions. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. \[object\] The transactions data for the income stream ordered by ascending date. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. string The `item_id` of the Item associated with this webhook, warning, or error string Plaid's unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the `account_id` is case sensitive. number The settled value of the transaction, denominated in the transaction's currency as stated in `iso_currency_code` or `unofficial_currency_code`. Positive values when money moves out of the account; negative values when money moves in. For example, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The string returned by the financial institution to describe the transaction. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. object Metadata on whether this income transaction is an outlier. boolean Indicates whether an income transaction amount is unusually high compared to the amounts for that stream. nullable, number The amount that the transaction differs from the stream average transaction amount. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. \[object\] If the Income Insights generation was successful but a subset of data could not be retrieved, this array will contain information about the errors causing information to be missing string The warning type, which will always be `CHECK_REPORT_WARNING` string The warning code identifies a specific kind of warning. `IDENTITY_UNAVAILABLE`: Account-owner information is not available. `TRANSACTIONS_UNAVAILABLE`: Transactions information associated with Credit and Depository accounts are unavailable. `USER_FRAUD_ALERT`: The user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Please note that when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: `IDENTITY_UNAVAILABLE`, `TRANSACTIONS_UNAVAILABLE`, `USER_FRAUD_ALERT` nullable, object An error object and associated `item_id` used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The `item_id` of the Item associated with this webhook, warning, or error Response Object ```json { "request_id": "LhQf0THi8SH1yJm", "report": { "report_id": "bbfc5174-5433-4648-8d93-9fec6a0c0966", "generated_time": "2022-01-31T22:47:53Z", "days_requested": 365, "user_summary": { "income_metrics": [ { "current": { "monthly": { "gross_income": 390, "net_income": 300 }, "annual": { "gross_income": 4680, "net_income": 3600 } }, "projected": { "monthly": { "gross_income": 300, "net_income": 300 }, "annual": { "gross_income": 3600, "net_income": 3600 } }, "iso_currency_code": "USD", "unofficial_currency_code": null } ] }, "income_streams": [ { "income_stream_id": "f17efbdd-caab-4278-8ece-963511cd3d51", "start_date": "2021-11-15", "end_date": "2022-01-15", "description": "PLAID INC DIRECT DEP PPD", "insights": { "income_category": { "primary": "EARNED_INCOME", "secondary": "SALARY" }, "pay_frequency": "MONTHLY", "income_provider": { "name": "Plaid Inc", "is_normalized": true }, "next_payment": { "date": "2022-12-15" }, "status": "ACTIVE" }, "income_metrics": { "current": { "monthly": { "gross_income": 390, "net_income": 300 }, "annual": { "gross_income": 4680, "net_income": 3600 } }, "projected": { "monthly": { "gross_income": 300, "net_income": 300 }, "annual": { "gross_income": 3600, "net_income": 3600 } }, "iso_currency_code": "USD", "unofficial_currency_code": null }, "transactions": [ { "transaction_id": "aH5klwqG3B19OMT7D6F24Syv8pdnJXmtZoKQ5", "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7", "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8", "amount": 100, "date": "2021-11-15", "original_description": "PLAID_INC_DIRECT_DEP_PPD 123A", "outlier": { "is_outlier": false }, "iso_currency_code": "USD", "unofficial_currency_code": null }, { "transaction_id": "mN3rQ5iH8BC41T6UjKL9oD2vWJpZqXFomGwY1", "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7", "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8", "amount": 100, "date": "2021-12-15", "original_description": "PLAID_INC_DIRECT_DEP_PPD 123B", "outlier": { "is_outlier": false }, "iso_currency_code": "USD", "unofficial_currency_code": null }, { "transaction_id": "zK9lDoR8uBH51PNQ3W4T6Mjy2VFXpGtJwsL4", "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7", "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8", "amount": 100, "date": "2022-01-31", "original_description": "PLAID_INC_DIRECT_DEP_PPD 123C", "outlier": { "is_outlier": false }, "iso_currency_code": "USD", "unofficial_currency_code": null } ] } ], "items": [ { "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7", "institution_name": "Plaid Bank", "institution_id": "ins_0", "last_updated_time": "2022-01-31T22:47:53Z", "bank_income_accounts": [], "bank_income_sources": [], "accounts": [ { "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8", "mask": "8888", "metadata": { "start_date": "2024-01-01", "end_date": "2024-07-16" }, "name": "Plaid Checking Account", "official_name": "Plaid Checking Account", "subtype": "checking", "type": "depository", "owners": [] } ] } ] }, "warnings": [] } ``` \=\*=\*=\*= #### /cra/check\_report/network\_insights/get  #### Retrieve network attributes for the user  This endpoint allows you to retrieve the Network Insights product for your user. You should call this endpoint after you've received a `CHECK_REPORT_READY` or a `USER_CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If the most recent consumer report for the user doesn’t have sufficient data to generate the report, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If you did not initialize Link with the `cra_network_attributes` product or have generated a report using [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , Plaid will generate the attributes when you call this endpoint. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . object Defines configuration options to generate Network Insights string The version of Network Insights. Required if using Network Insights. Possible values: `NI1` string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/network_insights/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw" }' ``` ```node try { const response = await client.craCheckReportNetworkInsightsGet({ user_id: 'usr_9nSp2KuZ2x4JDw', }); } catch (error) { // handle error } ``` ```python request = CraCheckReportNetworkInsightsGetRequest( user_id='usr_9nSp2KuZ2x4JDw' ) response = client.cra_check_report_network_insights_get(request) ``` ```ruby request = Plaid::CraCheckReportNetworkInsightsGetRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw' } ) response = client.cra_check_report_network_insights_get(request) ``` ```java CraCheckReportNetworkInsightsGetRequest request = new CraCheckReportNetworkInsightsGetRequest() .userId("usr_9nSp2KuZ2x4JDw"); Response response = client .craCheckReportNetworkInsightsGet(request) .execute(); ``` ```go request := plaid.NewCraCheckReportNetworkInsightsGetRequest() request.SetUserId("usr_9nSp2KuZ2x4JDw"); response, _, err := client.PlaidApi. CraCheckReportNetworkInsightsGet(ctx). CraCheckReportNetworkInsightsGetRequest(*request). Execute() ``` #### Response fields  object Contains data for the CRA Network Attributes Report. string The unique identifier associated with the report object. string The time when the report was generated. Format: `date-time` object A map of network attributes, where the key is a string, and the value is a float, int, or boolean. For a full list of attributes, contact your account manager. \[object\] The Items the end user connected in Link. string The ID for the institution the user linked. string The name of the institution the user linked. string The identifier for the Item. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. \[object\] If the Network Insights generation was successful but a subset of data could not be retrieved, this array will contain information about the errors causing information to be missing string The warning type, which will always be `CHECK_REPORT_WARNING` string The warning code identifies a specific kind of warning. `IDENTITY_UNAVAILABLE`: Account-owner information is not available. `TRANSACTIONS_UNAVAILABLE`: Transactions information associated with Credit and Depository accounts are unavailable. `USER_FRAUD_ALERT`: The user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Please note that when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: `IDENTITY_UNAVAILABLE`, `TRANSACTIONS_UNAVAILABLE`, `USER_FRAUD_ALERT` nullable, object An error object and associated `item_id` used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The `item_id` of the Item associated with this webhook, warning, or error Response Object ```json { "request_id": "LhQf0THi8SH1yJm", "report": { "report_id": "ee093cb0-e3f2-42d1-9dbc-8d8408964194", "generated_time": "2022-01-31T22:47:53Z", "network_attributes": { "plaid_conn_user_lifetime_lending_count": 5, "plaid_conn_user_lifetime_personal_lending_flag": 1, "plaid_conn_user_lifetime_cash_advance_primary_count": 0 }, "items": [ { "institution_id": "ins_0", "institution_name": "Plaid Bank", "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7" } ] } } ``` \=\*=\*=\*= #### /cra/check\_report/partner\_insights/get  #### Retrieve cash flow insights from partners  This endpoint allows you to retrieve the Partner Insights report for your user. You should call this endpoint after you've received a `CHECK_REPORT_READY` or a `USER_CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If the most recent consumer report for the user doesn’t have sufficient data to generate the base report, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If you did not initialize Link with the `credit_partner_insights` product or have generated a report using [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , we will call our partners to generate the insights when you call this endpoint. In this case, you may optionally provide parameters under `options` to configure which insights you want to receive. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . object Defines configuration to generate Partner Insights object The versions of Prism products to evaluate string The version of Prism FirstDetect. If not specified, will default to v3. Possible values: `3`, `null` string The version of Prism Detect Possible values: `4.1`, `4`, `null` string The version of Prism CashScore. If not specified, will default to v3. Possible values: `4.1`, `4`, `3`, `null` string The version of Prism Extend Possible values: `4.1`, `4`, `null` string The version of Prism Insights. If not specified, will default to v3. Possible values: `4.1`, `4`, `3`, `null` ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/partner_insights/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw" }' ``` ```node try { const response = await client.craCheckReportPartnerInsightsGet({ user_id: 'usr_9nSp2KuZ2x4JDw', }); } catch (error) { // handle error } ``` ```python request = CraCheckReportPartnerInsightsGetRequest( user_id='usr_9nSp2KuZ2x4JDw' ) response = client.cra_check_report_partner_insights_get(request) ``` ```ruby request = Plaid::CraCheckReportPartnerInsightsGetRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw' } ) response = client.cra_check_report_partner_insights_get(request) ``` ```java CraCheckReportPartnerInsightsGetRequest request = new CraCheckReportPartnerInsightsGetRequest() .userId("usr_9nSp2KuZ2x4JDw"); Response response = client .craCheckReportPartnerInsightsGet(request) .execute(); ``` ```go request := plaid.NewCraCheckReportPartnerInsightsGetRequest() request.SetUserId("usr_9nSp2KuZ2x4JDw") response, _, err := client.PlaidApi. CraCheckReportPartnerInsightsGet(ctx). CraCheckReportPartnerInsightsGetRequest(*request). Execute() ``` #### Response fields  object The Partner Insights report of the bank data for an end user. string A unique identifier associated with the Partner Insights object. string The time when the Partner Insights report was generated. Format: `date-time` nullable, string Client-generated identifier, which can be used by lenders to track loan applications. nullable, object The Prism Data insights for the user. nullable, object The data from the Insights product returned by Prism Data. integer The version of Prism Data's insights model used. object The Insights Result object is a map of cash flow attributes, where the key is a string, and the value is a float or string. For a full list of attributes, contact your account manager. The attributes may vary depending on the Prism version used. string The error returned by Prism for this product. nullable, object The data from the CashScore® product returned by Prism Data. deprecated, integer The version of Prism Data's cash score model used. This field is deprecated in favor of `model_version`. string The version of Prism Data's cash score model used. nullable, integer The score returned by Prism Data. Ranges from 1-999, with higher score indicating lower risk. \[string\] The reasons for an individual having risk according to the cash score. object An object containing metadata about the provided transactions. nullable, integer Number of days since the oldest transaction. nullable, integer Number of days since the latest transaction. nullable, integer Number of days since the latest credit transaction. nullable, integer Number of days since the latest debit transaction. nullable, integer Number of days since the oldest debit transaction. nullable, integer Number of days since the oldest credit transaction. nullable, integer Number of credit transactions. nullable, integer Number of debit transactions. nullable, integer Number of credit transactions in the last 30 days. nullable, integer Number of debit transactions in the last 30 days. string The error returned by Prism for this product. nullable, object The data from the CashScore® Extend product returned by Prism Data. string The version of Prism Data's CashScore® Extend model used. nullable, integer The score returned by Prism Data. Ranges from 1-999, with higher score indicating lower risk. \[string\] The reasons for an individual having risk according to the CashScore® Extend score. object An object containing metadata about the provided transactions. nullable, integer Number of days since the oldest transaction. nullable, integer Number of days since the latest transaction. nullable, integer Number of days since the latest credit transaction. nullable, integer Number of days since the latest debit transaction. nullable, integer Number of days since the oldest debit transaction. nullable, integer Number of days since the oldest credit transaction. nullable, integer Number of credit transactions. nullable, integer Number of debit transactions. nullable, integer Number of credit transactions in the last 30 days. nullable, integer Number of debit transactions in the last 30 days. string The error returned by Prism for this product. nullable, object The data from the FirstDetect product returned by Prism Data. deprecated, integer The version of Prism Data's FirstDetect model used. This field is deprecated in favor of `model_version`. string The version of Prism Data's FirstDetect model used. nullable, integer The score returned by Prism Data. Ranges from 1-999, with higher score indicating lower risk. \[string\] The reasons for an individual having risk according to the FirstDetect score. object An object containing metadata about the provided transactions. nullable, integer Number of days since the oldest transaction. nullable, integer Number of days since the latest transaction. nullable, integer Number of days since the latest credit transaction. nullable, integer Number of days since the latest debit transaction. nullable, integer Number of days since the oldest debit transaction. nullable, integer Number of days since the oldest credit transaction. nullable, integer Number of credit transactions. nullable, integer Number of debit transactions. nullable, integer Number of credit transactions in the last 30 days. nullable, integer Number of debit transactions in the last 30 days. string The error returned by Prism for this product. nullable, object The data from the CashScore® Detect product returned by Prism Data. string The version of Prism Data's CashScore® Detect model used. nullable, integer The score returned by Prism Data. Ranges from 1-999, with higher score indicating lower risk. \[string\] The reasons for an individual having risk according to the CashScore® Detect score. object An object containing metadata about the provided transactions. nullable, integer Number of days since the oldest transaction. nullable, integer Number of days since the latest transaction. nullable, integer Number of days since the latest credit transaction. nullable, integer Number of days since the latest debit transaction. nullable, integer Number of days since the oldest debit transaction. nullable, integer Number of days since the oldest credit transaction. nullable, integer Number of credit transactions. nullable, integer Number of debit transactions. nullable, integer Number of credit transactions in the last 30 days. nullable, integer Number of debit transactions in the last 30 days. string The error returned by Prism for this product. string Details on whether the Prism Data attributes succeeded or failed to be generated. \[object\] The list of Items used in the report along with the associated metadata about the Item. string The ID for the institution that the user linked. string The name of the institution the user linked. string The identifier for the item. \[object\] A list of accounts in the item string Plaid's unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the `account_id` is case sensitive. nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user. object An object containing metadata about the extracted account. nullable, string The date of the earliest extracted transaction, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). Format: `date` nullable, string The date of the most recent extracted transaction, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). Format: `date` string The name of the account nullable, string The official name of the bank account. string Valid account subtypes for depository accounts. For a list containing descriptions of each subtype, see [Account schemas](https://plaid.com/docs/api/accounts/index.html.md#StandaloneAccountType-depository) . Possible values: `checking`, `savings`, `hsa`, `cd`, `money market`, `paypal`, `prepaid`, `cash management`, `ebt`, `limited purpose checking`, `all` string The account type. This will always be `depository`. Possible values: `depository` \[object\] Data returned by the financial institution about the account owner or owners. Identity information is optional, so field may return an empty array. \[string\] A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's `names` array. \[object\] A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The phone number. boolean When `true`, identifies the phone number as the primary number on an account. string The type of phone number. Possible values: `home`, `work`, `office`, `mobile`, `mobile1`, `other` \[object\] A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The email address. boolean When `true`, identifies the email address as the primary email on an account. string The type of email account as described by the financial institution. Possible values: `primary`, `secondary`, `other` \[object\] Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. object Data about the components comprising an address. nullable, string The full city name nullable, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code boolean When `true`, identifies the address as the primary address on an account. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. \[object\] If the Partner Insights generation was successful but a subset of data could not be retrieved, this array will contain information about the errors causing information to be missing string The warning type, which will always be `CHECK_REPORT_WARNING` string The warning code identifies a specific kind of warning. `IDENTITY_UNAVAILABLE`: Account-owner information is not available. `TRANSACTIONS_UNAVAILABLE`: Transactions information associated with Credit and Depository accounts are unavailable. `USER_FRAUD_ALERT`: The user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Please note that when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: `IDENTITY_UNAVAILABLE`, `TRANSACTIONS_UNAVAILABLE`, `USER_FRAUD_ALERT` nullable, object An error object and associated `item_id` used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The `item_id` of the Item associated with this webhook, warning, or error Response Object ```json { "request_id": "LhQf0THi8SH1yJm", "report": { "report_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "client_report_id": "client_report_id_1221", "generated_time": "2022-01-31T22:47:53Z", "items": [ { "institution_id": "ins_109508", "institution_name": "Plaid Bank", "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr", "accounts": [ { "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8", "mask": "8888", "metadata": { "start_date": "2022-01-01", "end_date": "2022-01-31" }, "name": "Plaid Checking Account", "official_name": "Plaid Checking Account", "type": "depository", "subtype": "checking", "owners": [] } ] } ], "prism": { "insights": { "version": 3, "result": { "l6m_cumbal_acc": 1 } }, "cash_score": { "version": 3, "model_version": "3", "score": 900, "reason_codes": [ "CS03038" ], "metadata": { "max_age": 20, "min_age": 1, "min_age_credit": 0, "min_age_debit": 1, "max_age_debit": 20, "max_age_credit": 0, "num_trxn_credit": 0, "num_trxn_debit": 40, "l1m_credit_value_cnt": 0, "l1m_debit_value_cnt": 40 } }, "first_detect": { "version": 3, "model_version": "3", "score": 900, "reason_codes": [ "CS03038" ], "metadata": { "max_age": 20, "min_age": 1, "min_age_credit": 0, "min_age_debit": 1, "max_age_debit": 20, "max_age_credit": 0, "num_trxn_credit": 0, "num_trxn_debit": 40, "l1m_credit_value_cnt": 0, "l1m_debit_value_cnt": 40 } }, "status": "SUCCESS" } } } ``` \=\*=\*=\*= #### /cra/check\_report/pdf/get  #### Retrieve Consumer Reports as a PDF  [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) retrieves the most recent Consumer Report in PDF format. By default, the most recent Base Report (if it exists) for the user will be returned. To request that the most recent Partner Insights or Income Insights report be included in the PDF as well, use the `add-ons` field. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . \[string\] Use this field to include other reports in the PDF. Possible values: `cra_income_insights`, `cra_partner_insights` string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/pdf/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw" }' \ -o 'report.pdf' ``` ```node try { const response = await client.craCheckReportPDFGet({ user_id: 'usr_9nSp2KuZ2x4JDw', }); const pdf = response.buffer.toString('base64'); } catch (error) { // handle error } ``` ```python request = CraCheckReportPDFGetRequest( user_id='usr_9nSp2KuZ2x4JDw' ) response = client.cra_check_report_pdf_get(request) ``` ```ruby request = Plaid::CraCheckReportPDFGetRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw' } ) response = client.cra_check_report_pdf_get(request) ``` ```java CraCheckReportPDFGetRequest request = new CraCheckReportPDFGetRequest() .userId("usr_9nSp2KuZ2x4JDw"); Response response = client .craCheckReportPDFGet(request) .execute(); byte[] pdf = response.body().bytes(); ``` ```go request := plaid.NewCraCheckReportPDFGetRequest(); request.SetUserId("usr_9nSp2KuZ2x4JDw"); response, _, err := client.PlaidApi. CraCheckReportPDFGet(ctx). CraCheckReportPDFGetRequest(*request). Execute() ``` ##### Response  This endpoint returns binary PDF data. [View a sample Check Report PDF.](https://plaid.com/documents/sample-check-report.pdf) [View a sample Check Report PDF containing Income Insights.](https://plaid.com/documents/sample-check-report-with-income.pdf) \=\*=\*=\*= #### /cra/check\_report/cashflow\_insights/get  #### Retrieve cash flow insights from your user's banking data  This endpoint allows you to retrieve the Cashflow Insights report for your user. You should call this endpoint after you've received a `CHECK_REPORT_READY` or a `USER_CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If the most recent consumer report for the user doesn’t have sufficient data to generate the insights, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If you did not initialize Link with the `cra_cashflow_insights` product or have generated a report using [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , we will generate the insights when you call this endpoint. In this case, you may optionally provide parameters under `options` to configure which insights you want to receive. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . object Defines configuration options to generate Cashflow Insights string The version of cashflow attributes. Required if using Cash Flow Insights. Possible values: `CFI1` ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/cashflow_insights/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw" }' ``` ```node try { const response = await client.craCheckReportCashflowInsightsGet({ user_id: 'usr_9nSp2KuZ2x4JDw', }); } catch (error) { // handle error } ``` ```python request = CraCheckReportCashflowInsightsGetRequest( user_id='usr_9nSp2KuZ2x4JDw' ) response = client.cra_check_report_cashflow_insights_get(request) ``` ```ruby request = Plaid::CraCheckReportCashflowInsightsGetRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw' } ) response = client.cra_check_report_cashflow_insights_get(request) ``` ```java CraCheckReportCashflowInsightsGetRequest request = new CraCheckReportCashflowInsightsGetRequest() .userId("usr_9nSp2KuZ2x4JDw"); Response response = client .craCheckReportCashflowInsightsGet(request) .execute(); ``` ```go request := plaid.NewCraCheckReportCashflowInsightsGetRequest() request.SetUserId("usr_9nSp2KuZ2x4JDw") response, _, err := client.PlaidApi. CraCheckReportCashflowInsightsGet(ctx). CraCheckReportCashflowInsightsGetRequest(*request). Execute() ``` #### Response fields  object Contains data for the CRA Cashflow Insights Report. string The unique identifier associated with the report object. string The time when the report was generated. Format: `date-time` object A map of cash flow attributes, where the key is a string, and the value is a float, int, or boolean. The specific list of attributes will depend on the cash flow attributes version used. For a full list of attributes, contact your account manager. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. \[object\] If the Cashflow Insights generation was successful but a subset of data could not be retrieved, this array will contain information about the errors causing information to be missing string The warning type, which will always be `CHECK_REPORT_WARNING` string The warning code identifies a specific kind of warning. `IDENTITY_UNAVAILABLE`: Account-owner information is not available. `TRANSACTIONS_UNAVAILABLE`: Transactions information associated with Credit and Depository accounts are unavailable. `USER_FRAUD_ALERT`: The user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Please note that when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: `IDENTITY_UNAVAILABLE`, `TRANSACTIONS_UNAVAILABLE`, `USER_FRAUD_ALERT` nullable, object An error object and associated `item_id` used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The `item_id` of the Item associated with this webhook, warning, or error Response Object ```json { "request_id": "LhQf0THi8SH1yJm", "report": { "report_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "generated_time": "2022-01-31T22:47:53Z", "attributes": { "cash_reliance_atm_withdrawal_amt_cv_90d": 180.1 } } } ``` \=\*=\*=\*= #### /cra/check\_report/lend\_score/get  #### Retrieve the LendScore from your user's banking data  This endpoint allows you to retrieve the LendScore report for your user. You should call this endpoint after you've received a `CHECK_REPORT_READY` or a `USER_CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If the most recent consumer report for the user doesn’t have sufficient data to generate the insights, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If you did not initialize Link with the `cra_lend_score` product or call [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) with the `cra_lend_score` product, Plaid will generate the insights when you call this endpoint. In this case, you may optionally provide parameters under `options` to configure which insights you want to receive. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . object Defines configuration options to generate the LendScore string The version of the LendScore to use. Required if using LendScore. Possible values: `LS1` ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/lend_score/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw" }' ``` ```node try { const response = await client.craCheckReportLendScoreGet({ user_id: 'usr_9nSp2KuZ2x4JDw', }); } catch (error) { // handle error } ``` ```python request = CraCheckReportLendScoreGetRequest( user_id='usr_9nSp2KuZ2x4JDw' ) response = client.cra_check_report_lend_score_get(request) ``` ```ruby request = Plaid::CraCheckReportLendScoreGetRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw' } ) response = client.cra_check_report_lend_score_get(request) ``` ```java CraCheckReportLendScoreGetRequest request = new CraCheckReportLendScoreGetRequest() .userId("usr_9nSp2KuZ2x4JDw"); Response response = client .craCheckReportLendScoreGet(request) .execute(); ``` ```go request := plaid.NewCraCheckReportLendScoreGetRequest() request.SetUserId("usr_9nSp2KuZ2x4JDw") response, _, err := client.PlaidApi. CraCheckReportLendScoreGet(ctx). CraCheckReportLendScoreGetRequest(*request). Execute() ``` #### Response fields  object Contains data for the CRA LendScore Report. string The unique identifier associated with the report object. string The time when the report was generated. Format: `date-time` nullable, object The results of the LendScore nullable, integer The score returned by the LendScore model. Will be an integer in the range 1 to 99. Higher scores indicate lower credit risk. \[string\] The reasons for an individual having risk according to the LendScore. For a full list of possible reason codes and a mapping of reason codes to human-readable reasons, contact your Plaid Account Manager. Different LendScore versions will use different sets of reason codes. nullable, string Human-readable description of why the LendScore could not be computed. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. \[object\] If the LendScore generation was successful but a subset of data could not be retrieved, this array will contain information about the errors causing information to be missing string The warning type, which will always be `CHECK_REPORT_WARNING` string The warning code identifies a specific kind of warning. `IDENTITY_UNAVAILABLE`: Account-owner information is not available. `TRANSACTIONS_UNAVAILABLE`: Transactions information associated with Credit and Depository accounts are unavailable. `USER_FRAUD_ALERT`: The user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Please note that when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: `IDENTITY_UNAVAILABLE`, `TRANSACTIONS_UNAVAILABLE`, `USER_FRAUD_ALERT` nullable, object An error object and associated `item_id` used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The `item_id` of the Item associated with this webhook, warning, or error Response Object ```json { "request_id": "LhQf0THi8SH1yJm", "report": { "report_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "generated_time": "2022-01-31T22:47:53Z", "lend_score": { "score": 80, "reason_codes": [ "PCS0221", "PCS0223" ] } } } ``` \=\*=\*=\*= #### /cra/check\_report/verification/get  #### Retrieve various home lending reports for a user.  This endpoint allows you to retrieve home lending reports for a user. To obtain a VoA or Employment Refresh report, you need to make sure that `cra_base_report` is included in the `products` parameter when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) or [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . You should call this endpoint after you've received a `CHECK_REPORT_READY` or a `USER_CHECK_REPORT_READY` webhook, either after the Link session for the user or after calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If the most recent consumer report for the user doesn’t have sufficient data to generate the report, or the consumer report has expired, you will receive an error indicating that you should create a new consumer report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) ." #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . required, \[string\] Specifies which types of home lending reports are expected in the response Possible values: `VOA`, `EMPLOYMENT_REFRESH`, `INCOME` object Defines configuration options for the Employment Refresh Report. required, integer The number of days of data to request for the report. This field is required if an Employment Refresh Report is requested. Maximum is 731. Maximum: `731` string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/verification/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "reports_requested": ["VOA", "EMPLOYMENT_REFRESH"], "employment_refresh_options": { "days_requested": 60 }, "user_id": "usr_9nSp2KuZ2x4JDw" }' ``` ```node try { const response = await client.craCheckReportVerificationGet({ user_id: 'usr_9nSp2KuZ2x4JDw', reports_requested: ['VOA', 'EMPLOYMENT_REFRESH'], employment_refresh_options: { days_requested: 60, }, }); } catch (error) { // handle error } ``` ```python request = CraCheckReportVerificationGetRequest( user_id='usr_9nSp2KuZ2x4JDw', reports_requested=['VOA', 'EMPLOYMENT_REFRESH'], employment_refresh_options={ 'days_requested': 60, }, ) response = client.cra_check_report_verification_get(request) ``` ```ruby request = Plaid::CraCheckReportVerificationGetRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw', reports_requested: ['VOA', 'EMPLOYMENT_REFRESH'], employment_refresh_options: { days_requested: 60, }, } ) response = client.cra_check_report_verification_get(request) ``` ```java CraCheckReportVerificationGetEmploymentRefreshOptions employment_refresh_options = new CraCheckReportVerificationGetEmploymentRefreshOptions() .daysRequested(60); CraCheckReportVerificationGetRequest request = new CraCheckReportVerificationGetRequest() .userId("usr_9nSp2KuZ2x4JDw") .reportsRequested(Arrays.asList(CraCheckReportVerificationGetReportType.VOA, CraCheckReportVerificationGetReportType.EMPLOYMENT_REFRESH)) .employmentRefreshOptions(employment_refresh_options); Response response = client .craCheckReportVerificationGet(request) .execute(); ``` ```go employmentRefreshOptions := plaid.CraCheckReportVerificationGetEmploymentRefreshOptions{ DaysRequested: 60, } reportsRequested := []plaid.CraCheckReportVerificationGetReportType{ plaid.CraCheckReportVerificationGetReportType_VOA, plaid.CraCheckReportVerificationGetReportType_EMPLOYMENT_REFRESH, } request := plaid.NewCraCheckReportVerificationGetRequest() request.SetUserId("usr_9nSp2KuZ2x4JDw") request.SetReportsRequested(reportsRequested) request.SetEmploymentRefreshOptions(employmentRefreshOptions) response, _, err := client.PlaidApi. CraCheckReportVerificationGet(ctx). CraCheckReportVerificationGetRequest(*request). Execute() ``` #### Response fields  object Contains data for the CRA Home Lending Report. string The unique identifier associated with the Home Lending Report object. This ID will be the same as the Base Report ID. string A unique token that can be shared with GSEs in order to provide them access to the report. This is automatically created during report generation when GSE options are specified. nullable, string Client-generated identifier, which can be used by lenders to track loan applications. nullable, object An object representing a VOA report. string The date and time when the VOA Report was created, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (e.g. "2018-04-12T03:32:11Z"). Format: `date-time` number The number of days of transaction history that the VOA report covers. \[object\] Data returned by Plaid about each of the Items included in the Base Report. \[object\] Data about each of the accounts open on the Item. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the `account_id` is case sensitive. object VOA Report information about an account's balances. nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get`; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. \[object\] Calculated data about the historical balances on the account. Available for `credit` and `depository` type accounts. number The total amount of funds in the account, calculated from the `current` balance in the `balance` object by subtracting inflows and adding back outflows according to the posted date of each transaction. Format: `double` string The date of the calculated historical balance, in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The ISO-4217 currency code of the balance. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the balance. Always `null` if `iso_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, number The average balance in the account over the last 30 days. Calculated using the derived historical balances. Format: `double` nullable, number The average balance in the account over the last 60 days. Calculated using the derived historical balances. Format: `double` number The number of net NSF fee transactions in the time range for the report in the given account (not counting any fees that were reversed within the time range). \[object\] The information about previously submitted valid dispute statements by the consumer deprecated, string (Deprecated) A unique identifier (UUID) of the consumer dispute that can be used for troubleshooting string Date of the disputed field (e.g. transaction date), in an ISO 8601 format (YYYY-MM-DD) Format: `date` string Type of data being disputed by the consumer Possible values: `TRANSACTION`, `BALANCE`, `IDENTITY`, `OTHER` string Text content of dispute nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user. string The name of the account, either assigned by the user or by the financial institution itself. nullable, string The official name of the account as given by the financial institution. string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` number The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account. object Transaction data associated with the account. \[object\] Transaction history associated with the account. string The ID of the account in which this transaction occurred. number The settled value of the transaction, denominated in the transaction's currency, as stated in `iso_currency_code` or `unofficial_currency_code`. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. Format: `double` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string The string returned by the financial institution to describe the transaction. nullable, object Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. See the [taxonomy csv file](https://plaid.com/documents/credit-category-taxonomy.csv) for a full list of credit categories. string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string The check number of the transaction. This field is only populated for check transactions. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). Format: `date` nullable, string The date on which the transaction took place, in IS0 8601 format. object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. nullable, string The merchant name, as enriched by Plaid from the `name` field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be `null`. boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. nullable, string The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. nullable, string The latest timeframe provided by the FI, in an ISO 8601 format (YYYY-MM-DD). Format: `date` nullable, string The earliest timeframe provided by the FI, in an ISO 8601 format (YYYY-MM-DD). Format: `date` \[object\] Data returned by the financial institution about the account owner or owners. \[string\] A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's `names` array. \[object\] A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The phone number. boolean When `true`, identifies the phone number as the primary number on an account. string The type of phone number. Possible values: `home`, `work`, `office`, `mobile`, `mobile1`, `other` \[object\] A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The email address. boolean When `true`, identifies the email address as the primary email on an account. string The type of email account as described by the financial institution. Possible values: `primary`, `secondary`, `other` \[object\] Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. object Data about the components comprising an address. nullable, string The full city name nullable, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code boolean When `true`, identifies the address as the primary address on an account. nullable, string How an asset is owned. `association`: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. `individual`: Ownership by an individual. `joint`: Joint ownership by multiple parties. `trust`: Ownership by a revocable or irrevocable trust. Possible values: `null`, `individual`, `joint`, `association`, `trust` nullable, object A set of fields describing the investments data on an account. \[object\] Quantities and values of securities held in the investment account. Map to the `securities` array for security details. string The Plaid `account_id` associated with the holding. string The Plaid `security_id` associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The `security_id` for the same security will typically be the same across different institutions, but this is not guaranteed. The `security_id` does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. number The last price given by the institution for this security. Format: `double` nullable, string The date at which `institution_price` was current. Format: `date` number The value of the holding, as reported by the institution. Format: `double` nullable, number The original total value of the holding. This field is calculated by Plaid as the sum of the purchase price of all of the shares in the holding. Format: `double` number The total quantity of the asset held, as reported by the financial institution. If the security is an option, `quantity` will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts. Format: `double` nullable, string The ISO-4217 currency code of the holding. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the holding. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. \[object\] Details of specific securities held in the investment account. string A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the `security_id` is case sensitive. The `security_id` may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. nullable, string A descriptive name for the security, suitable for display. nullable, string 12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . nullable, string 9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . nullable, string An identifier given to the security by the institution. nullable, string If `institution_security_id` is present, this field indicates the Plaid `institution_id` of the institution to whom the identifier belongs. nullable, string The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available. nullable, string The security type of the holding. Valid security types are: `cash`: Cash, currency, and money market funds `cryptocurrency`: Digital or virtual currencies `derivative`: Options, warrants, and other derivative instruments `equity`: Domestic and foreign equities `etf`: Multi-asset exchange-traded investment funds `fixed income`: Bonds and certificates of deposit (CDs) `loan`: Loans and loan receivables `mutual fund`: Open- and closed-end vehicles pooling funds of multiple investors `other`: Unknown or other investment types \[object\] Transaction history on the investment account. string The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the `investment_transaction_id` is case sensitive. string The `account_id` of the account against which this transaction posted. nullable, string The `security_id` to which this transaction is related. string The [ISO 8601](https://wikipedia.org/wiki/ISO_8601) posting date for the transaction. Format: `date` string The institution’s description of the transaction. number The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions. Format: `double` number The complete value of the transaction. Positive values when cash is debited, e.g. purchases of stock; negative values when cash is credited, e.g. sales of stock. Treatment remains the same for cash-only movements unassociated with securities. Format: `double` number The price of the security at which this transaction occurred. Format: `double` nullable, number The combined value of all fees applied to this transaction Format: `double` string Value is one of the following: `buy`: Buying an investment `sell`: Selling an investment `cancel`: A cancellation of a pending transaction `cash`: Activity that modifies a cash position `fee`: A fee on the account `transfer`: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer For descriptions of possible transaction types and subtypes, see the [Investment transaction types schema](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Possible values: `buy`, `sell`, `cancel`, `cash`, `fee`, `transfer` string For descriptions of possible transaction types and subtypes, see the [Investment transaction types schema](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Possible values: `account fee`, `adjustment`, `assignment`, `buy`, `buy to cover`, `contribution`, `deposit`, `distribution`, `dividend`, `dividend reinvestment`, `exercise`, `expire`, `fund fee`, `interest`, `interest receivable`, `interest reinvestment`, `legal fee`, `loan payment`, `long-term capital gain`, `long-term capital gain reinvestment`, `management fee`, `margin expense`, `merger`, `miscellaneous fee`, `non-qualified dividend`, `non-resident tax`, `pending credit`, `pending debit`, `qualified dividend`, `rebalance`, `return of principal`, `request`, `sell`, `sell short`, `send`, `short-term capital gain`, `short-term capital gain reinvestment`, `spin off`, `split`, `stock distribution`, `tax`, `tax withheld`, `trade`, `transfer`, `transfer fee`, `trust fee`, `unqualified gain`, `withdrawal` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the holding. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. string The full financial institution name associated with the Item. string The id of the financial institution associated with the Item. string The `item_id` of the Item associated with this webhook, warning, or error string The date and time when this Item’s data was last retrieved from the financial institution, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` object Attributes for the VOA report. nullable, object Total amount of debit transactions into the report's accounts in the time period of the report. This field only takes into account USD transactions from the accounts. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the report's accounts in the time period of the report. This field only takes into account USD transactions from the accounts. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object An object representing an Employment Refresh Report. string The date and time when the Employment Refresh Report was created, in ISO 8601 format (e.g. "2018-04-12T03:32:11Z"). Format: `date-time` number The number of days of transaction history that the Employment Refresh Report covers. \[object\] Data returned by Plaid about each of the Items included in the Employment Refresh Report. \[object\] Data about each of the accounts open on the Item. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the `account_id` is case sensitive. string The name of the account, either assigned by the user or by the financial institution itself. nullable, string The official name of the account as given by the financial institution. string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` \[object\] Transaction history associated with the account for the Employment Refresh Report. Note that this transaction differs from a Base Report transaction in that it will only be deposits, and the amounts will be omitted. string The ID of the account in which this transaction occurred. string The string returned by the financial institution to describe the transaction. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( `YYYY-MM-DD` ). Format: `date` boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. string The full financial institution name associated with the Item. string The id of the financial institution associated with the Item. string The `item_id` of the Item associated with this webhook, warning, or error string The date and time when this Item’s data was last retrieved from the financial institution, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. \[object\] If the home lending report generation was successful but a subset of data could not be retrieved, this array will contain information about the errors causing information to be missing. string The warning type, which will always be `CHECK_REPORT_WARNING` string The warning code identifies a specific kind of warning. `IDENTITY_UNAVAILABLE`: Account-owner information is not available. `TRANSACTIONS_UNAVAILABLE`: Transactions information associated with Credit and Depository accounts are unavailable. `USER_FRAUD_ALERT`: The user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. Please note that when a fraud alert is in place, the recipient of the consumer report has an obligation to verify the consumer’s identity. Possible values: `IDENTITY_UNAVAILABLE`, `TRANSACTIONS_UNAVAILABLE`, `USER_FRAUD_ALERT` nullable, object An error object and associated `item_id` used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The `item_id` of the Item associated with this webhook, warning, or error Response Object ```json { "request_id": "LhQf0THi8SH1yJm", "report": { "report_id": "028e8404-a013-4a45-ac9e-002482f9cafc", "client_report_id": "client_report_id_1221", "voa": { "generated_time": "2023-03-30T18:27:37Z", "days_requested": 90, "attributes": { "total_inflow_amount": { "amount": -345.12, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_outflow_amount": { "amount": 235.12, "iso_currency_code": "USD", "unofficial_currency_code": null } }, "items": [ { "accounts": [ { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "unofficial_currency_code": null, "historical_balances": [ { "current": 110, "date": "2023-03-29", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 125.55, "date": "2023-03-28", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 80.13, "date": "2023-03-27", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 246.11, "date": "2023-03-26", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 182.71, "date": "2023-03-25", "iso_currency_code": "USD", "unofficial_currency_code": null } ], "average_balance_30_days": 200, "average_balance_60_days": 150, "average_balance_90_days": 125, "nsf_overdraft_transactions_count": 0 }, "consumer_disputes": [], "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "type": "depository", "subtype": "checking", "days_available": 90, "transactions_insights": { "all_transactions": [ { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": 89.4, "date": "2023-03-27", "iso_currency_code": "USD", "original_description": "SparkFun", "pending": false, "transaction_id": "4zBRq1Qem4uAPnoyKjJNTRQpQddM4ztlo1PLD", "unofficial_currency_code": null }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": 12, "date": "2023-03-28", "iso_currency_code": "USD", "original_description": "McDonalds #3322", "pending": false, "transaction_id": "dkjL41PnbKsPral79jpxhMWdW55gkPfBkWpRL", "unofficial_currency_code": null }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": 4.33, "date": "2023-03-28", "iso_currency_code": "USD", "original_description": "Starbucks", "pending": false, "transaction_id": "a84ZxQaWDAtDL3dRgmazT57K7jjN3WFkNWMDy", "unofficial_currency_code": null }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "amount": -500, "date": "2023-03-29", "iso_currency_code": "USD", "original_description": "United Airlines **** REFUND ****", "pending": false, "transaction_id": "xG9jbv3eMoFWepzB7wQLT3LoLggX5Duy1Gbe5", "unofficial_currency_code": null } ], "end_date": "2024-07-31", "start_date": "2024-07-01" }, "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "region": "NY", "street": "2992 Cameron Road", "postal_code": "14236" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "region": "CA", "street": "2493 Leisure Lane", "postal_code": "93405-2255" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholder1@example.com", "primary": false, "type": "secondary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "+1 111-555-3333", "primary": false, "type": "home" }, { "data": "+1 111-555-4444", "primary": false, "type": "work" }, { "data": "+1 111-555-5555", "primary": false, "type": "mobile" } ] } ], "ownership_type": null } ], "institution_name": "First Platypus Bank", "institution_id": "ins_109508", "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7", "last_update_time": "2023-03-30T18:25:26Z" } ] }, "employment_refresh": { "generated_time": "2023-03-30T18:27:37Z", "days_requested": 60, "items": [ { "accounts": [ { "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8", "name": "Plaid Money Market", "official_name": "Plaid Platinum Standard 1.85% Interest Money Market", "type": "depository", "subtype": "money market", "transactions": [ { "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8", "original_description": "ACH Electronic CreditGUSTO PAY 123456", "date": "2023-03-30", "pending": false, "transaction_id": "gGQgjoeyqBF89PND6K14Sow1wddZBmtLomJ78" } ] }, { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "type": "depository", "subtype": "checking", "transactions": [ { "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v", "original_description": "United Airlines **** REFUND ****", "date": "2023-03-29", "pending": false, "transaction_id": "xG9jbv3eMoFWepzB7wQLT3LoLggX5Duy1Gbe5" } ] } ], "institution_name": "First Platypus Bank", "institution_id": "ins_109508", "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7", "last_update_time": "2023-03-30T18:25:26Z" } ] } }, "warnings": [] } ``` \=\*=\*=\*= #### /cra/check\_report/verification/pdf/get  #### Retrieve Consumer Reports as a Verification PDF  The [/cra/check\_report/verification/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationpdfget) endpoint retrieves the most recent Consumer Report in PDF format, specifically formatted for Home Lending verification use cases. Before calling this endpoint, ensure that you've created a VOA report through Link or the [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) endpoint, and have received a `CHECK_REPORT_READY` or a `USER_CHECK_REPORT_READY` webhook. The response to [/cra/check\_report/verification/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationpdfget) is the PDF binary data. The `request_id` is returned in the `Plaid-Request-ID` header. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . required, string The type of verification PDF report to fetch. Possible values: `voa`, `employment_refresh` string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/verification/pdf/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw", "report_requested": "VOA" }' \ -o 'verification.pdf' ``` ```node try { const response = await client.craCheckReportVerificationPDFGet({ user_id: 'usr_9nSp2KuZ2x4JDw', report_requested: 'VOA', }); const pdf = response.buffer.toString('base64'); } catch (error) { // handle error } ``` ```python request = CraCheckReportVerificationPDFGetRequest( user_id='usr_9nSp2KuZ2x4JDw', report_requested='VOA', ) response = client.cra_check_report_verification_pdf_get(request) ``` ```ruby request = Plaid::CraCheckReportVerificationPDFGetRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw', report_requested: 'VOA', } ) response = client.cra_check_report_verification_pdf_get(request) ``` ```java CraCheckReportVerificationPDFGetRequest request = new CraCheckReportVerificationPDFGetRequest() .userId("usr_9nSp2KuZ2x4JDw") .reportRequested("VOA"); Response response = client .craCheckReportVerificationPDFGet(request) .execute(); byte[] pdf = response.body().bytes(); ``` ```go request := plaid.NewCraCheckReportVerificationPDFGetRequest() request.SetUserId("usr_9nSp2KuZ2x4JDw") request.SetReportRequested("VOA") response, _, err := client.PlaidApi. CraCheckReportVerificationPDFGet(ctx). CraCheckReportVerificationPDFGetRequest(*request). Execute() ``` ##### Response  This endpoint returns binary PDF data. View a sample [Home Lending Report (aka VoA Report)](https://plaid.com/documents/sample-mortgage-verification-voa.pdf) or [Employment Refresh](https://plaid.com/documents/sample-mortgage-verification-voe.pdf) report. \=\*=\*=\*= #### /cra/check\_report/create  #### Refresh or create a Consumer Report  Use [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) to refresh data in an existing report. A Consumer Report will last for 24 hours before expiring; you should call any `/get` endpoints on the report before it expires. If a report expires, you can call [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) again to re-generate it and refresh the data in the report. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . required, string The destination URL to which webhooks will be sent Format: `url` required, integer The number of days of data to request for the report. Default value is 365; maximum is 731; minimum is 180. If a value lower than 180 is provided, a minimum of 180 days of history will be requested. Maximum: `731` integer The minimum number of days of data required for the report to be successfully generated. Maximum: `184` string Client-generated identifier, which can be used by lenders to track loan applications. \[string\] Specifies a list of products that will be eagerly generated when creating the report (in addition to the Base Report, which is always eagerly generated). These products will be made available before a success webhook is sent. Use this option to minimize response latency for product `/get` endpoints. Note that specifying `cra_partner_insights` in this field will trigger a billable event. Other products are not billed until the respective reports are fetched via product-specific `/get` endpoints. Min items: `1` Possible values: `cra_income_insights`, `cra_cashflow_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_lend_score` object Defines configuration options to generate a Base Report deprecated, string Client-generated identifier, which can be used by lenders to track loan applications. This field is deprecated. Use the `client_report_id` field at the top level of the request instead. object Specifies options for creating reports that can be shared with GSEs for mortgage verification. required, \[string\] Specifies which types of reports should be made available to GSEs. Possible values: `VOA`, `EMPLOYMENT_REFRESH` boolean Indicates that the report must include identity information. If identity information is not available, the report will fail. object Defines configuration options to generate Cashflow Insights string The version of cashflow attributes. Required if using Cash Flow Insights. Possible values: `CFI1` object Defines configuration to generate Partner Insights. object The versions of Prism products to evaluate string The version of Prism FirstDetect. If not specified, will default to v3. Possible values: `3`, `null` string The version of Prism Detect Possible values: `4.1`, `4`, `null` string The version of Prism CashScore. If not specified, will default to v3. Possible values: `4.1`, `4`, `3`, `null` string The version of Prism Extend Possible values: `4.1`, `4`, `null` string The version of Prism Insights. If not specified, will default to v3. Possible values: `4.1`, `4`, `3`, `null` object Defines configuration options to generate the LendScore string The version of the LendScore to use. Required if using LendScore. Possible values: `LS1` object Defines configuration options to generate Network Insights string The version of Network Insights. Required if using Network Insights. Possible values: `NI1` boolean Indicates that investment data should be extracted from the linked account(s). object Defines configuration options to generate Income Insights. object Filters the returned income streams based on the specified income categories. If no filters are requested, streams from the following default set of categories are returned: * `EARNED_INCOME.*` (`EARNED_INCOME.SALARY`, `EARNED_INCOME.GIG_ECONOMY`, `EARNED_INCOME.SELF_EMPLOYED`) * `BENEFITS.DISABILITY` * `RETIREMENT.*` (`RETIREMENT.GOVERNMENT_DERIVED`, `RETIREMENT.PRIVATE_RETIREMENT`, `RETIREMENT.PLAN_DISTRIBUTION`) The final list of income categories is generated by adding the `included_categories`, then removing the `excluded_categories`. Priority is given to `excluded_categories` in the case of collisions. Filter patterns supported: * `*`: All categories * `PRIMARY.*`: All categories within the specified primary category * `PRIMARY.SECONDARY`: A specific income category For a list of income categories, see the [Income V2 Category Taxonomy](https://plaid.com/documents/income-v2-category-taxonomy.csv) . required, \[string\] Includes income streams matching the specified categories. \[string\] Excludes income streams matching the specified categories. required, string The version of Income Insights to use. Possible values: `II2` required, string Describes the reason you are generating a Consumer Report for this user. When calling `/link/token/create`, this field is required when using Plaid Check (CRA) products; invalid if not using Plaid Check (CRA) products. `ACCOUNT_REVIEW_CREDIT`: In connection with a consumer credit transaction for the review or collection of an account pursuant to FCRA Section 604(a)(3)(A). `ACCOUNT_REVIEW_NON_CREDIT`: For a legitimate business need of the information to review a non-credit account provided primarily for personal, family, or household purposes to determine whether the consumer continues to meet the terms of the account pursuant to FCRA Section 604(a)(3)(F)(2). `EXTENSION_OF_CREDIT`: In connection with a credit transaction initiated by and involving the consumer pursuant to FCRA Section 604(a)(3)(A). `LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING`: For a legitimate business need in connection with a business transaction initiated by the consumer primarily for personal, family, or household purposes in connection with a property rental assessment pursuant to FCRA Section 604(a)(3)(F)(i). `LEGITIMATE_BUSINESS_NEED_OTHER`: For a legitimate business need in connection with a business transaction made primarily for personal, family, or household initiated by the consumer pursuant to FCRA Section 604(a)(3)(F)(i). `WRITTEN_INSTRUCTION_PREQUALIFICATION`: In accordance with the written instructions of the consumer pursuant to FCRA Section 604(a)(2), to evaluate an application’s profile to make an offer to the consumer. `WRITTEN_INSTRUCTION_OTHER`: In accordance with the written instructions of the consumer pursuant to FCRA Section 604(a)(2), such as when an individual agrees to act as a guarantor or assumes personal liability for a consumer, business, or commercial loan. `ELIGIBILITY_FOR_GOVT_BENEFITS`: In connection with an eligibility determination for a government benefit where the entity is required to consider an applicant’s financial status pursuant to FCRA Section 604(a)(3)(D). Possible values: `ACCOUNT_REVIEW_CREDIT`, `ACCOUNT_REVIEW_NON_CREDIT`, `EXTENSION_OF_CREDIT`, `LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING`, `LEGITIMATE_BUSINESS_NEED_OTHER`, `WRITTEN_INSTRUCTION_PREQUALIFICATION`, `WRITTEN_INSTRUCTION_OTHER`, `ELIGIBILITY_FOR_GOVT_BENEFITS` ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw", "webhook": "https://sample-web-hook.com", "days_requested": 365, "consumer_report_permissible_purpose": "LEGITIMATE_BUSINESS_NEED_OTHER" }' ``` ```node try { const response = await client.craCheckReportCreate({ user_id: 'usr_9nSp2KuZ2x4JDw', webhook: 'https://sample-web-hook.com', days_requested: 365, consumer_report_permissible_purpose: 'LEGITIMATE_BUSINESS_NEED_OTHER', }); } catch (error) { // handle error } ``` ```python request = CraCheckReportCreateRequest( user_id='usr_9nSp2KuZ2x4JDw', webhook='https://sample-web-hook.com', days_requested=365, consumer_report_permissible_purpose='LEGITIMATE_BUSINESS_NEED_OTHER', ) response = client.cra_check_report_create(request) ``` ```ruby request = Plaid::CraCheckReportCreateRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw', webhook: 'https://sample-web-hook.com', days_requested: 365, consumer_report_permissible_purpose: 'LEGITIMATE_BUSINESS_NEED_OTHER', } ) response = client.cra_check_report_create(request) ``` ```java CraCheckReportCreateRequest request = new CraCheckReportCreateRequest() .userId("usr_9nSp2KuZ2x4JDw") .webhook("https://sample-web-hook.com") .daysRequested(365) .consumerReportPermissiblePurpose("LEGITIMATE_BUSINESS_NEED_OTHER"); Response response = client .craCheckReportCreate(request) .execute(); ``` ```go request := plaid.NewCraCheckReportCreateRequest() request.SetUserId("usr_9nSp2KuZ2x4JDw") request.SetWebhook("https://sample-web-hook.com") request.SetDaysRequested(365) request.SetConsumerReportPermissiblePurpose(plaid.CONSUMERREPORTPERMISSIBLEPURPOSE_LEGITIMATE_BUSINESS_NEED_OTHER) response, _, err := client.PlaidApi. CraCheckReportCreate(ctx). CraCheckReportCreateRequest(*request). Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "LhQf0THi8SH1yJm" } ``` \=\*=\*=\*= #### /cra/monitoring\_insights/get  #### Retrieve a Monitoring Insights Report  This endpoint allows you to retrieve a Cash Flow Updates report by passing in the `user_id` referred to in the webhook you received. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . required, string Describes the reason you are generating a Consumer Report for this user. `ACCOUNT_REVIEW_CREDIT`: In connection with a consumer credit transaction for the review or collection of an account pursuant to FCRA Section 604(a)(3)(A). `WRITTEN_INSTRUCTION_OTHER`: In accordance with the written instructions of the consumer pursuant to FCRA Section 604(a)(2), such as when an individual agrees to act as a guarantor or assumes personal liability for a consumer, business, or commercial loan. Possible values: `ACCOUNT_REVIEW_CREDIT`, `WRITTEN_INSTRUCTION_OTHER` string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/cra/monitoring_insights/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw", "consumer_report_permissible_purpose": "EXTENSION_OF_CREDIT" }' ``` ```node try { const response = await client.craMonitoringInsightsGet({ user_id: 'usr_9nSp2KuZ2x4JDw', consumer_report_permissible_purpose: 'EXTENSION_OF_CREDIT', }); } catch (error) { // handle error } ``` ```python request = CraMonitoringInsightsGetRequest( user_id='usr_9nSp2KuZ2x4JDw', consumer_report_permissible_purpose='EXTENSION_OF_CREDIT', ) response = client.cra_monitoring_insights_get(request) ``` ```ruby request = Plaid::CraMonitoringInsightsGetRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw', consumer_report_permissible_purpose: 'EXTENSION_OF_CREDIT', } ) response = client.cra_monitoring_insights_get(request) ``` ```java CraMonitoringInsightsGetRequest request = new CraMonitoringInsightsGetRequest() .userId("usr_9nSp2KuZ2x4JDw") .consumerReportPermissiblePurpose("EXTENSION_OF_CREDIT"); Response response = client .craMonitoringInsightsGet(request) .execute(); ``` ```go request := plaid.NewCraMonitoringInsightsGetRequest( "user-environment-12345678-abcd-4bcd-abcd-1234567890ab", "EXTENSION_OF_CREDIT" ) response, _, err := client.PlaidApi. CraMonitoringInsightsGet(ctx). CraMonitoringInsightsGetRequest(*request). Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. string A unique ID identifying a User Monitoring Insights Report. Like all Plaid identifiers, this ID is case sensitive. \[object\] An array of Monitoring Insights Items associated with the user. string The date and time when the specific insights were generated (per-item), in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (e.g. "2018-04-12T03:32:11Z"). Format: `date-time` string The `item_id` of the Item associated with the insights string The id of the financial institution associated with the Item. string The full financial institution name associated with the Item. object An object with details of the Monitoring Insights Item's status. string Enum for the status of the Item's insights Possible values: `AVAILABLE`, `FAILED`, `PENDING` nullable, string A reason for why a Monitoring Insights Report is not available. This field will only be populated when the `status_code` is not `AVAILABLE` nullable, object An object representing the Monitoring Insights for the given Item object An object representing the income subcategory of the report object Details about about the total monthly income number The aggregated income of the last 30 days object Details about the number of income sources number The number of income sources currently detected object An object representing the predicted average monthly net income amount. This amount reflects the funds deposited into the account and may not include any withheld income such as taxes or other payroll deductions number The current forecasted monthly income object An object representing the historical annual income amount. number The current historical annual income \[object\] The income sources for this Item. Each entry in the array is a single income source string A unique identifier for an income source string The most common name or original description for the underlying income transactions string The income category. `BANK_INTEREST`: Interest earned from a bank account. `BENEFIT_OTHER`: Government benefits other than retirement, unemployment, child support, or disability. Currently used only in the UK, to represent benefits such as Cost of Living Payments. `CASH`: Deprecated and used only for existing legacy implementations. Has been replaced by `CASH_DEPOSIT` and `TRANSFER_FROM_APPLICATION`. `CASH_DEPOSIT`: A cash or check deposit. `CHILD_SUPPORT`: Child support payments received. `GIG_ECONOMY`: Income earned as a gig economy worker, e.g. driving for Uber, Lyft, Postmates, DoorDash, etc. `LONG_TERM_DISABILITY`: Disability payments, including Social Security disability benefits. `OTHER`: Income that could not be categorized as any other income category. `MILITARY`: Veterans benefits. Income earned as salary for serving in the military (e.g. through DFAS) will be classified as `SALARY` rather than `MILITARY`. `RENTAL`: Income earned from a rental property. Income may be identified as rental when the payment is received through a rental platform, e.g. Airbnb; rent paid directly by the tenant to the property owner (e.g. via cash, check, or ACH) will typically not be classified as rental income. `RETIREMENT`: Payments from private retirement systems, pensions, and government retirement programs, including Social Security retirement benefits. `SALARY`: Payment from an employer to an earner or other form of permanent employment. `TAX_REFUND`: A tax refund. `TRANSFER_FROM_APPLICATION`: Deposits from a money transfer app, such as Venmo, Cash App, or Zelle. `UNEMPLOYMENT`: Unemployment benefits. In the UK, includes certain low-income benefits such as the Universal Credit. Possible values: `SALARY`, `UNEMPLOYMENT`, `CASH`, `GIG_ECONOMY`, `RENTAL`, `CHILD_SUPPORT`, `MILITARY`, `RETIREMENT`, `LONG_TERM_DISABILITY`, `BANK_INTEREST`, `CASH_DEPOSIT`, `TRANSFER_FROM_APPLICATION`, `TAX_REFUND`, `BENEFIT_OTHER`, `OTHER` string The last detected transaction date for this income source Format: `date` object An object representing the loan exposure subcategory of the report object Details regarding the number of loan payments number The current number of loan payments made in the last 30 days number The number of loan disbursements detected in the last 30 days object Details regarding the number of unique loan payment merchants number The current number of unique loan payment merchants detected in the last 30 days \[object\] Data about each of the accounts open on the Item. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the `account_id` is case sensitive. object Information about an account's balances. nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get`; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the oldest acceptable balance when making a request to `/accounts/balance/get`. This field is only used and expected when the institution is `ins_128026` (Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an `INVALID_REQUEST` error with the code of `INVALID_FIELD` will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See [account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of account types. If the balance that is pulled is older than the given timestamp for Items with this field required, an `INVALID_REQUEST` error with the code of `LAST_UPDATED_DATETIME_OUT_OF_RANGE` will be returned with the most recent timestamp for the requested account contained in the response. Format: `date-time` nullable, number The average historical balance for the entire report Format: `double` \[object\] The average historical balance of each calendar month string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). object This contains an amount, denominated in the currency specified by either `iso_currency_code` or `unofficial_currency_code` number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, number The average historical balance from the most recent 30 days Format: `double` \[object\] The information about previously submitted valid dispute statements by the consumer deprecated, string (Deprecated) A unique identifier (UUID) of the consumer dispute that can be used for troubleshooting string Date of the disputed field (e.g. transaction date), in an ISO 8601 format (YYYY-MM-DD) Format: `date` string Type of data being disputed by the consumer Possible values: `TRANSACTION`, `BALANCE`, `IDENTITY`, `OTHER` string Text content of dispute nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user. object Metadata about the extracted account. nullable, string The beginning of the range of the financial institution provided data for the account, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). Format: `date` nullable, string The end of the range of the financial institution provided data for the account, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). Format: `date` string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` number The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account. \[object\] Transaction history associated with the account. Transaction history returned by endpoints such as `/transactions/get` or `/investments/transactions/get` will be returned in the top-level `transactions` field instead. Some transactions may have their details masked in accordance to the FCRA. These will appear with a `credit_category` of `MASKED_TRANSACTION_CATEGORY`. string The ID of the account in which this transaction occurred. number The settled value of the transaction, denominated in the transaction's currency, as stated in `iso_currency_code` or `unofficial_currency_code`. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. Format: `double` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string The string returned by the financial institution to describe the transaction. nullable, object Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases. See the [taxonomy csv file](https://plaid.com/documents/credit-category-taxonomy.csv) for a full list of credit categories. string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string The check number of the transaction. This field is only populated for check transactions. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). Format: `date` nullable, string The date on which the transaction took place, in IS0 8601 format. object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. nullable, string The merchant name, as enriched by Plaid from the `name` field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be `null`. boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. nullable, string The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. \[object\] Data returned by the financial institution about the account owner or owners. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same `owner` object, not in multiple owner objects within the array. This array can also be empty if no owners are found. \[string\] A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's `names` array. \[object\] A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The phone number. boolean When `true`, identifies the phone number as the primary number on an account. string The type of phone number. Possible values: `home`, `work`, `office`, `mobile`, `mobile1`, `other` \[object\] A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The email address. boolean When `true`, identifies the email address as the primary email on an account. string The type of email account as described by the financial institution. Possible values: `primary`, `secondary`, `other` \[object\] Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. object Data about the components comprising an address. nullable, string The full city name nullable, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code boolean When `true`, identifies the address as the primary address on an account. nullable, string How an asset is owned. `association`: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. `individual`: Ownership by an individual. `joint`: Joint ownership by multiple parties. `trust`: Ownership by a revocable or irrevocable trust. Possible values: `null`, `individual`, `joint`, `association`, `trust` deprecated, object Calculated insights derived from transaction-level data. This field has been deprecated in favor of [Base Report attributes aggregated across accounts](https://plaid.com/docs/api/products/check/index.html.md#cra-check_report-base_report-get-response-report-attributes) and will be removed in a future release. nullable, string Date of the earliest transaction for the account. Format: `date` nullable, string Date of the most recent transaction for the account. Format: `date` integer Number of days days available for the account. number Average number of days between sequential transactions \[object\] Longest gap between sequential transactions in a time period. This array can include multiple time periods. string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` nullable, integer Largest number of days between sequential transactions for this time period. \[object\] The number of debits into the account. This array will be empty for non-depository accounts. string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` integer The number of credits or debits out of the account for this time period. \[object\] Average amount of debit transactions into the account in a time period. This array will be empty for non-depository accounts. This field only takes into account USD transactions from the account. string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` object This contains an amount, denominated in the currency specified by either `iso_currency_code` or `unofficial_currency_code` number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. \[object\] The number of outflows from the account. This array will be empty for non-depository accounts. string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` integer The number of credits or debits out of the account for this time period. \[object\] Average amount of transactions out of the account in a time period. This array will be empty for non-depository accounts. This field only takes into account USD transactions from the account. string The start date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of this time period. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` object This contains an amount, denominated in the currency specified by either `iso_currency_code` or `unofficial_currency_code` number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. integer Number of days with no transactions object Calculated attributes derived from transaction-level data. nullable, boolean Prediction indicator of whether the account is a primary account. Only one account per account type across the items connected will have a value of true. nullable, number Value ranging from 0-1. The higher the score, the more confident we are of the account being the primary account. integer The number of net NSF fee transactions for a given account within the report time range (not counting any fees that were reversed within the time range). integer The number of net NSF fee transactions within the last 30 days for a given account (not counting any fees that were reversed within the time range). integer The number of net NSF fee transactions within the last 60 days for a given account (not counting any fees that were reversed within the time range). integer The number of net NSF fee transactions within the last 90 days for a given account (not counting any fees that were reversed within the time range). nullable, object Total amount of debit transactions into the account in the time period of the report. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of debit transactions into the account in the last 30 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of debit transactions into the account in the last 60 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of debit transactions into the account in the last 90 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the account in the time period of the report. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the account in the last 30 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the account in the last 60 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. nullable, object Total amount of credit transactions into the account in the last 90 days. This field will be empty for non-depository accounts. This field only takes into account USD transactions from the account. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. Response Object ```json { "user_insights_id": "028e8404-a013-4a45-ac9e-002482f9cafc", "items": [ { "date_generated": "2023-03-30T18:27:37Z", "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7", "institution_id": "ins_0", "institution_name": "Plaid Bank", "status": { "status_code": "AVAILABLE" }, "insights": { "income": { "income_sources": [ { "income_source_id": "f17efbdd-caab-4278-8ece-963511cd3d51", "income_description": "PLAID_INC_DIRECT_DEP_PPD", "income_category": "SALARY", "last_transaction_date": "2023-03-30" } ], "forecasted_monthly_income": { "current_amount": 12000 }, "total_monthly_income": { "current_amount": 20000.31 }, "historical_annual_income": { "current_amount": 144000 }, "income_sources_counts": { "current_count": 1 } }, "loans": { "loan_payments_counts": { "current_count": 1 }, "loan_payment_merchants_counts": { "current_count": 1 }, "loan_disbursements_count": 1 } }, "accounts": [ { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "attributes": { "total_inflow_amount": { "amount": -2500, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_inflow_amount_30d": { "amount": -1000, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_inflow_amount_60d": { "amount": -2500, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_inflow_amount_90d": { "amount": -2500, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_outflow_amount": { "amount": 2500, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_outflow_amount_30d": { "amount": 1000, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_outflow_amount_60d": { "amount": 2500, "iso_currency_code": "USD", "unofficial_currency_code": null }, "total_outflow_amount_90d": { "amount": 2500, "iso_currency_code": "USD", "unofficial_currency_code": null } }, "balances": { "available": 5000, "average_balance": 4956.12, "average_monthly_balances": [ { "average_balance": { "amount": 4956.12, "iso_currency_code": "USD", "unofficial_currency_code": null }, "end_date": "2024-07-31", "start_date": "2024-07-01" } ], "current": 5000, "iso_currency_code": "USD", "limit": null, "most_recent_thirty_day_average_balance": 4956.125, "unofficial_currency_code": null }, "consumer_disputes": [], "days_available": 365, "mask": "1208", "metadata": { "start_date": "2024-01-01", "end_date": "2024-07-16" }, "name": "Checking", "official_name": "Plaid checking", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "postal_code": "93405-2255", "region": "CA", "street": "2493 Leisure Lane" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholder1@example.com", "primary": false, "type": "secondary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "+1 111-555-3333", "primary": false, "type": "home" }, { "data": "+1 111-555-4444", "primary": false, "type": "work" }, { "data": "+1 111-555-5555", "primary": false, "type": "mobile" } ] } ], "ownership_type": null, "subtype": "checking", "transactions": [ { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 37.07, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-12", "date_posted": "2024-07-12T00:00:00Z", "date_transacted": "2024-07-12", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Amazon", "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM", "pending": false, "transaction_id": "XA7ZLy8rXzt7D3j9B6LMIgv5VxyQkAhbKjzmp", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 51.61, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-12", "date_posted": "2024-07-12T00:00:00Z", "date_transacted": "2024-07-12", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Domino's", "original_description": "DOMINO's XXXX 111-222-3333", "pending": false, "transaction_id": "VEPeMbWqRluPVZLQX4MDUkKRw41Ljzf9gyLBW", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 7.55, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_FURNITURE_AND_HARDWARE", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-12", "date_posted": "2024-07-12T00:00:00Z", "date_transacted": "2024-07-12", "iso_currency_code": "USD", "location": { "address": null, "city": "Chicago", "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "IKEA", "original_description": "IKEA CHICAGO", "pending": false, "transaction_id": "6GQZARgvroCAE1eW5wpQT7w3oB6nvzi8DKMBa", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 12.87, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_SPORTING_GOODS", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-12", "date_posted": "2024-07-12T00:00:00Z", "date_transacted": "2024-07-12", "iso_currency_code": "USD", "location": { "address": null, "city": "Redlands", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "CA", "state": "CA", "store_number": null, "zip": null }, "merchant_name": "Nike", "original_description": "NIKE REDLANDS CA", "pending": false, "transaction_id": "DkbmlP8BZxibzADqNplKTeL8aZJVQ1c3WR95z", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 44.21, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-12", "date_posted": "2024-07-12T00:00:00Z", "date_transacted": "2024-07-12", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": null, "original_description": "POKE BROS * POKE BRO IL", "pending": false, "transaction_id": "RpdN7W8GmRSdjZB9Jm7ATj4M86vdnktapkrgL", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 36.82, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_DISCOUNT_STORES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-13", "date_posted": "2024-07-13T00:00:00Z", "date_transacted": "2024-07-13", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Family Dollar", "original_description": "FAMILY DOLLAR", "pending": false, "transaction_id": "5AeQWvo5KLtAD9wNL68PTdAgPE7VNWf5Kye1G", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 13.27, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-13", "date_posted": "2024-07-13T00:00:00Z", "date_transacted": "2024-07-13", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Instacart", "original_description": "INSTACART HTTPSINSTACAR CA", "pending": false, "transaction_id": "Jjlr3MEVg1HlKbdkZj39ij5a7eg9MqtB6MWDo", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 36.03, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-13", "date_posted": "2024-07-13T00:00:00Z", "date_transacted": "2024-07-13", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": null, "original_description": "POKE BROS * POKE BRO IL", "pending": false, "transaction_id": "kN9KV7yAZJUMPn93KDXqsG9MrpjlyLUL6Dgl8", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 54.74, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-13", "date_posted": "2024-07-13T00:00:00Z", "date_transacted": "2024-07-13", "iso_currency_code": "USD", "location": { "address": null, "city": "Whittier", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "CA", "state": "CA", "store_number": null, "zip": null }, "merchant_name": "Smart & Final", "original_description": "POS SMART AND FINAL 111 WHITTIER CA", "pending": false, "transaction_id": "lPvrweZAMqHDar43vwWKs547kLZVEzfpogGVJ", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 37.5, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-13", "date_posted": "2024-07-13T00:00:00Z", "date_transacted": "2024-07-13", "iso_currency_code": "USD", "location": { "address": "1627 N 24th St", "city": "Phoenix", "country": null, "lat": null, "lon": null, "postal_code": "85008", "region": "AZ", "state": "AZ", "store_number": null, "zip": "85008" }, "merchant_name": "Taqueria El Guerrerense", "original_description": "TAQUERIA EL GUERRERO PHOENIX AZ", "pending": false, "transaction_id": "wka74WKqngiyJ3pj7dl5SbpLGQBZqyCPZRDbP", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 41.42, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Amazon", "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM", "pending": false, "transaction_id": "BBGnV4RkerHjn8WVavGyiJbQ95VNDaC4M56bJ", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": -1077.93, "check_number": null, "credit_category": { "detailed": "INCOME_OTHER", "primary": "INCOME" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Lyft", "original_description": "LYFT TRANSFER", "pending": false, "transaction_id": "3Ej78yKJlQu1Abw7xzo4U4JR6pmwzntZlbKDK", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 47.17, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": "Whittier", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "CA", "state": "CA", "store_number": null, "zip": null }, "merchant_name": "Smart & Final", "original_description": "POS SMART AND FINAL 111 WHITTIER CA", "pending": false, "transaction_id": "rMzaBpJw8jSZRJQBabKdteQBwd5EaWc7J9qem", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 12.37, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": "Whittier", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "CA", "state": "CA", "store_number": null, "zip": null }, "merchant_name": "Smart & Final", "original_description": "POS SMART AND FINAL 111 WHITTIER CA", "pending": false, "transaction_id": "zWPZjkmzynTyel89ZjExS59DV6WAaZflNBJ56", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 44.18, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": "Portland", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "OR", "state": "OR", "store_number": "1111", "zip": null }, "merchant_name": "Safeway", "original_description": "SAFEWAY #1111 PORTLAND OR 111111", "pending": false, "transaction_id": "K7qzx1nP8ptqgwaRMbxyI86XrqADMluRpkWx5", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 45.37, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-14", "date_posted": "2024-07-14T00:00:00Z", "date_transacted": "2024-07-14", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Uber Eats", "original_description": "UBER EATS", "pending": false, "transaction_id": "qZrdzLRAgNHo5peMdD9xIzELl3a1NvcgrPAzL", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 15.22, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Amazon", "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM", "pending": false, "transaction_id": "NZzx4oRPkAHzyRekpG4PTZkWnBPqEyiy6pB1M", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 26.33, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Domino's", "original_description": "DOMINO's XXXX 111-222-3333", "pending": false, "transaction_id": "x84eNArKbESz8Woden6LT3nvyogeJXc64Pp35", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 39.8, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_DISCOUNT_STORES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Family Dollar", "original_description": "FAMILY DOLLAR", "pending": false, "transaction_id": "dzWnyxwZ4GHlZPGgrNyxiMG7qd5jDgCJEz5jL", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 45.06, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Instacart", "original_description": "INSTACART HTTPSINSTACAR CA", "pending": false, "transaction_id": "4W7eE9rZqMToDArbPeLNIREoKpdgBMcJbVNQD", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 34.91, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": "Whittier", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "CA", "state": "CA", "store_number": null, "zip": null }, "merchant_name": "Smart & Final", "original_description": "POS SMART AND FINAL 111 WHITTIER CA", "pending": false, "transaction_id": "j4yqDjb7QwS7woGzqrgDIEG1NaQVZwf6Wmz3D", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 49.78, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": "Portland", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "OR", "state": "OR", "store_number": "1111", "zip": null }, "merchant_name": "Safeway", "original_description": "SAFEWAY #1111 PORTLAND OR 111111", "pending": false, "transaction_id": "aqgWnze7xoHd6DQwLPnzT5dgPKjB1NfZ5JlBy", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 54.24, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-15", "date_posted": "2024-07-15T00:00:00Z", "date_transacted": "2024-07-15", "iso_currency_code": "USD", "location": { "address": null, "city": "Portland", "country": null, "lat": null, "lon": null, "postal_code": null, "region": "OR", "state": "OR", "store_number": "1111", "zip": null }, "merchant_name": "Safeway", "original_description": "SAFEWAY #1111 PORTLAND OR 111111", "pending": false, "transaction_id": "P13aP8b7nmS3WQoxg1PMsdvMK679RNfo65B4G", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 41.79, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_ONLINE_MARKETPLACES", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-16", "date_posted": "2024-07-16T00:00:00Z", "date_transacted": "2024-07-16", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Amazon", "original_description": "AMZN Mktp US*11111111 Amzn.com/bill WA AM", "pending": false, "transaction_id": "7nZMG6pXz8SADylMqzx7TraE4qjJm7udJyAGm", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 33.86, "check_number": null, "credit_category": { "detailed": "FOOD_RETAIL_GROCERIES", "primary": "FOOD_RETAIL" }, "date": "2024-07-16", "date_posted": "2024-07-16T00:00:00Z", "date_transacted": "2024-07-16", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "Instacart", "original_description": "INSTACART HTTPSINSTACAR CA", "pending": false, "transaction_id": "MQr3ap7PWEIrQG7bLdaNsxyBV7g1KqCL6pwoy", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 27.08, "check_number": null, "credit_category": { "detailed": "DINING_DINING", "primary": "DINING" }, "date": "2024-07-16", "date_posted": "2024-07-16T00:00:00Z", "date_transacted": "2024-07-16", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": null, "original_description": "POKE BROS * POKE BRO IL", "pending": false, "transaction_id": "eBAk9dvwNbHPZpr8W69dU3rekJz47Kcr9BRwl", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 25.94, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_FURNITURE_AND_HARDWARE", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-16", "date_posted": "2024-07-16T00:00:00Z", "date_transacted": "2024-07-16", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": "The Home Depot", "original_description": "THE HOME DEPOT", "pending": false, "transaction_id": "QLx4jEJZb9SxRm7aWbjAio3LrgZ5vPswm64dE", "unofficial_currency_code": null }, { "account_id": "NZzx4oRPkAHzyRekpG4PTZkoGpNAR4uypaj1E", "account_owner": null, "amount": 27.57, "check_number": null, "credit_category": { "detailed": "GENERAL_MERCHANDISE_OTHER_GENERAL_MERCHANDISE", "primary": "GENERAL_MERCHANDISE" }, "date": "2024-07-16", "date_posted": "2024-07-16T00:00:00Z", "date_transacted": "2024-07-16", "iso_currency_code": "USD", "location": { "address": null, "city": null, "country": null, "lat": null, "lon": null, "postal_code": null, "region": null, "state": null, "store_number": null, "zip": null }, "merchant_name": null, "original_description": "The Press Club", "pending": false, "transaction_id": "ZnQ1ovqBldSQ6GzRbroAHLdQP68BrKceqmAjX", "unofficial_currency_code": null } ], "type": "depository" } ] } ], "request_id": "m8MDnv9okwxFNBV" } ``` \=\*=\*=\*= #### /cra/monitoring\_insights/subscribe  #### Subscribe to Monitoring Insights  This endpoint allows you to subscribe to insights for a user's linked CRA Item, which are updated between one and four times per day (best-effort). In the current Cash Flow Updates beta experience, only one Item per user may be subscribed for monitoring updates. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string The item ID to subscribe for Cash Flow Updates. required, string URL to which Plaid will send Cash Flow Updates webhooks, for example when the requested Cash Flow Updates report is ready. Format: `url` \[string\] Income categories to include in Cash Flow Updates. If empty or `null`, this field will default to including all possible categories. Possible values: `SALARY`, `UNEMPLOYMENT`, `CASH`, `GIG_ECONOMY`, `RENTAL`, `CHILD_SUPPORT`, `MILITARY`, `RETIREMENT`, `LONG_TERM_DISABILITY`, `BANK_INTEREST`, `CASH_DEPOSIT`, `TRANSFER_FROM_APPLICATION`, `TAX_REFUND`, `BENEFIT_OTHER`, `OTHER` string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/cra/monitoring_insights/subscribe \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "webhook": "https://example.com/webhook", "income_categories": ["SALARY"] }' ``` ```node try { const response = await client.craMonitoringInsightsSubscribe({ user_id: 'usr_9nSp2KuZ2x4JDw', item_id: 'eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6', webhook: 'https://example.com/webhook', income_categories: [CreditBankIncomeCategory.Salary], }); } catch (error) { // handle error } ``` ```python request = CraMonitoringInsightsSubscribeRequest( user_id='usr_9nSp2KuZ2x4JDw', item_id='eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6', webhook='https://example.com/webhook', income_categories=[CreditBankIncomeCategory('SALARY')], ) response = client.cra_monitoring_insights_subscribe(request) ``` ```ruby request = Plaid::CraMonitoringInsightsSubscribeRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw', item_id: 'eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6', webhook: 'https://example.com/webhook', income_categories: ['SALARY'], } ) response = client.cra_monitoring_insights_subscribe(request) ``` ```java CraMonitoringInsightsSubscribeRequest request = new CraMonitoringInsightsSubscribeRequest() .userId("usr_9nSp2KuZ2x4JDw") .itemId("eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6") .webhook("https://example.com/webhook") .incomeCategories(Arrays.asList(CreditBankIncomeCategory.SALARY)); Response response = client .craMonitoringInsightsSubscribe(request) .execute(); ``` ```go request := plaid.NewCraMonitoringInsightsSubscribeRequest( "user-environment-12345678-abcd-4bcd-abcd-1234567890ab", "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "https://example.com/webhook", []string{"SALARY"}, ) response, _, err := client.PlaidApi. CraMonitoringInsightsSubscribe(ctx). CraMonitoringInsightsSubscribeRequest(*request). Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. string A unique identifier for the subscription. Response Object ```json { "subscription_id": "f17efbdd-caab-4278-8ece-963511cd3d51", "request_id": "GVzMdiDd8DDAQK4" } ``` \=\*=\*=\*= #### /cra/monitoring\_insights/unsubscribe  #### Unsubscribe from Monitoring Insights  This endpoint allows you to unsubscribe from previously subscribed Monitoring Insights. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string A unique identifier for the subscription. ```bash curl -X POST https://sandbox.plaid.com/cra/monitoring_insights/unsubscribe \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "subscription_id": "user-environment-12345678-abcd-4bcd-abcd-1234567890ab", "webhook": "https://example.com/webhook" }' ``` ```node try { const response = await client.craMonitoringInsightsUnsubscribe({ subscription_id: '"f17efbdd-caab-4278-8ece-963511cd3d51"', }); } catch (error) { // handle error } ``` ```python request = CraMonitoringInsightsUnsubscribeRequest( subscription_id='"f17efbdd-caab-4278-8ece-963511cd3d51"', ) response = client.cra_monitoring_insights_unsubscribe(request) ``` ```ruby request = Plaid::CraMonitoringInsightsUnsubscribeRequest.new( { subscription_id: '"f17efbdd-caab-4278-8ece-963511cd3d51"', } ) response = client.cra_monitoring_insights_unsubscribe(request) ``` ```java CraMonitoringInsightsUnsubscribeRequest request = new CraMonitoringInsightsUnsubscribeRequest() .subscriptionId("f17efbdd-caab-4278-8ece-963511cd3d51"); Response response = client .craMonitoringInsightsUnsubscribe(request) .execute(); ``` ```go request := plaid.NewCraMonitoringInsightsUnsubscribeRequest( "f17efbdd-caab-4278-8ece-963511cd3d51", ) response, _, err := client.PlaidApi. CraMonitoringInsightsUnsubscribe(ctx). CraMonitoringInsightsUnsubscribeRequest(*request). Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "GVzMdiDd8DDAQK4" } ``` ### Webhooks  When you create a new report, either by creating a Link token with a Plaid Check product, or by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , Plaid Check will start generating a report for you. When the report has been created (or the report creation fails), Plaid Check will let you know by sending you either a `CHECK_REPORT: USER_CHECK_REPORT_READY` or `CHECK_REPORT: USER_CHECK_REPORT_FAILED` webhook. Customers who first called [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) after December 10, 2025 will receive the `USER_CHECK_REPORT_READY` / `USER_CHECK_REPORT_FAILED` webhooks. Customers who integrated before this date will receive the older `CHECK_REPORT_READY` / `CHECK_REPORT_FAILED` webhooks. For more details, see [new User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . \=\*=\*=\*= #### USER\_CHECK\_REPORT\_READY  Fired when the Check Report are ready to be retrieved. Once this webhook has fired, the report will be available to retrieve for 24 hours. #### Properties  string `CHECK_REPORT` string `USER_CHECK_REPORT_READY` string The `user_id` associated with the user whose data is being requested. This is received by calling `user/create`. \[string\] Specifies a list of products that have successfully been generated for the report. Possible values: `cra_base_report`, `cra_income_insights`, `cra_cashflow_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_monitoring`, `cra_lend_score` \[string\] Specifies a list of products that have failed to generate for the report. Additional detail on what caused the failure can be found by calling the product /get endpoint. Possible values: `cra_base_report`, `cra_income_insights`, `cra_cashflow_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_monitoring`, `cra_lend_score` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "CHECK_REPORT", "webhook_code": "USER_CHECK_REPORT_READY", "user_id": "usr_8c3ZbDBYjaqUXZ", "successful_products": [ "cra_base_report" ], "environment": "production" } ``` \=\*=\*=\*= #### USER\_CHECK\_REPORT\_FAILED  Fired when a Check Report has failed to generate #### Properties  string `CHECK_REPORT` string `USER_CHECK_REPORT_FAILED` string The `user_id` associated with the user whose data is being requested. This is received by calling user/create. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "CHECK_REPORT", "webhook_code": "USER_CHECK_REPORT_FAILED", "user_id": "usr_8c3ZbDBYjaqUXZ", "environment": "production" } ``` \=\*=\*=\*= #### CHECK\_REPORT\_READY  Fired when the Check Report are ready to be retrieved. Once this webhook has fired, the report will be available to retrieve for 24 hours. #### Properties  string `CHECK_REPORT` string `CHECK_REPORT_READY` string The `user_id` corresponding to the user the webhook has fired for. \[string\] Specifies a list of products that have successfully been generated for the report. Possible values: `cra_base_report`, `cra_income_insights`, `cra_cashflow_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_monitoring`, `cra_lend_score` \[string\] Specifies a list of products that have failed to generate for the report. Additional detail on what caused the failure can be found by calling the product /get endpoint. Possible values: `cra_base_report`, `cra_income_insights`, `cra_cashflow_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_monitoring`, `cra_lend_score` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "CHECK_REPORT", "webhook_code": "CHECK_REPORT_READY", "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "successful_products": [ "cra_base_report" ], "environment": "production" } ``` \=\*=\*=\*= #### CHECK\_REPORT\_FAILED  Fired when a Check Report has failed to generate. To get more details, call [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) and check for non-null `error` objects on the associated Items in the response. These `error` objects will contain more details on why the Item is in an error state and how to resolve it. After resolving the errors, you can try to re-generate the report. #### Properties  string `CHECK_REPORT` string `CHECK_REPORT_FAILED` string The `user_id` corresponding to the user the webhook has fired for. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "CHECK_REPORT", "webhook_code": "CHECK_REPORT_FAILED", "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "environment": "production" } ``` ### Cash flow updates webhooks  These webhooks are specific to the Cash Flow Updates (beta) product. All webhooks in this section except for `CASH_FLOW_INSIGHTS_UPDATED` are legacy webhooks and will only be fired for customers who integrated with Plaid Check before December 10, 2025. For newer integrations, `CASH_FLOW_INSIGHTS_UPDATED` has replaced the other webhooks. For more details, see [New user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . \=\*=\*=\*= #### CASH\_FLOW\_INSIGHTS\_UPDATED  For each item on an enabled user, this webhook will fire up to four times a day with status information. This webhook will not fire immediately upon enrollment in Cash Flow Updates. The payload may contain an `insights` array with insights that have been detected, if any (e.g. `LOW_BALANCE_DETECTED`, `LARGE_DEPOSIT_DETECTED`). Upon receiving the webhook, call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights. #### Properties  string `CASH_FLOW_UPDATES` string `CASH_FLOW_INSIGHTS_UPDATED` string Enum for the status of the insights Possible values: `AVAILABLE`, `FAILED` string The `user_id` associated with the user whose data is being requested. This is received by calling `user/create`. \[string\] Array containing the insights detected within the generated report, if any. Possible values include: `LARGE_DEPOSIT_DETECTED`: signaling a deposit over $5,000 `LOW_BALANCE_DETECTED`: signaling a balance below $100 `NEW_LOAN_PAYMENT_DETECTED`: signaling a new loan payment `NSF_OVERDRAFT_DETECTED`: signaling an NSF overdraft Possible values: `LARGE_DEPOSIT_DETECTED`, `LOW_BALANCE_DETECTED`, `NEW_LOAN_PAYMENT_DETECTED`, `NSF_OVERDRAFT_DETECTED` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "CASH_FLOW_UPDATES", "webhook_code": "CASH_FLOW_INSIGHTS_UPDATED", "status": "AVAILABLE", "user_id": "usr_6009db6e", "insights": [ "LARGE_DEPOSIT_DETECTED", "LOW_BALANCE_DETECTED", "NEW_LOAN_PAYMENT_DETECTED", "NSF_OVERDRAFT_DETECTED" ], "environment": "sandbox" } ``` \=\*=\*=\*= #### INSIGHTS\_UPDATED  For each user's Item enabled for Cash Flow Updates, this webhook will fire between one and four times a day with information on the status of the update. This webhook will not fire immediately upon enrollment in Cash Flow Updates. Upon receiving the webhook, call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights. At approximately the same time as the `INSIGHTS_UPDATED` webhook, any event-driven `CASH_FLOW_UPDATES` webhooks (e.g. `LOW_BALANCE_DETECTED`, `LARGE_DEPOSIT_DETECTED`) that were triggered by the update will also fire. This webhook has been replaced by the `CASH_FLOW_INSIGHTS_UPDATED` webhook for all customers who began using Plaid Check on or after December 10, 2025. #### Properties  string `CASH_FLOW_UPDATES` string `INSIGHTS_UPDATED` string Enum for the status of the insights Possible values: `AVAILABLE`, `FAILED` string The `user_id` that the report is associated with string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "CASH_FLOW_UPDATES", "webhook_code": "INSIGHTS_UPDATED", "status": "AVAILABLE", "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334", "environment": "production" } ``` \=\*=\*=\*= #### LARGE\_DEPOSIT\_DETECTED  For each user's item enabled for Cash Flow Updates, this webhook will fire when an update detects a deposit over $5,000. Upon receiving the webhook, call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights. #### Properties  string `CASH_FLOW_UPDATES` string `LARGE_DEPOSIT_DETECTED` string Enum for the status of the insights Possible values: `AVAILABLE`, `FAILED` string The `user_id` that the report is associated with string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "CASH_FLOW_UPDATES", "webhook_code": "LARGE_DEPOSIT_DETECTED", "status": "AVAILABLE", "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334", "environment": "production" } ``` \=\*=\*=\*= #### LOW\_BALANCE\_DETECTED  For each user's item enabled for Cash Flow Updates, this webhook will fire when an update detects a balance below $100. Upon receiving the webhook, call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights. #### Properties  string `CASH_FLOW_UPDATES` string `LOW_BALANCE_DETECTED` string Enum for the status of the insights Possible values: `AVAILABLE`, `FAILED` string The `user_id` that the report is associated with string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "CASH_FLOW_UPDATES", "webhook_code": "LOW_BALANCE_DETECTED", "status": "AVAILABLE", "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334", "environment": "production" } ``` \=\*=\*=\*= #### NEW\_LOAN\_PAYMENT\_DETECTED  For each user's item enabled for Cash Flow Updates, this webhook will fire when an update detects a new loan payment. Upon receiving the webhook, call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights. #### Properties  string `CASH_FLOW_UPDATES` string `NEW_LOAN_PAYMENT_DETECTED` string Enum for the status of the insights Possible values: `AVAILABLE`, `FAILED` string The `user_id` that the report is associated with string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "CASH_FLOW_UPDATES", "webhook_code": "NEW_LOAN_PAYMENT_DETECTED", "status": "AVAILABLE", "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334", "environment": "production" } ``` \=\*=\*=\*= #### NSF\_OVERDRAFT\_DETECTED  For each user's item enabled for Cash Flow Updates, this webhook will fire when an update includes an NSF overdraft transaction. Upon receiving the webhook, call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights. #### Properties  string `CASH_FLOW_UPDATES` string `NSF_OVERDRAFT_DETECTED` string Enum for the status of the insights Possible values: `AVAILABLE`, `FAILED` string The `user_id` that the report is associated with string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "CASH_FLOW_UPDATES", "webhook_code": "NSF_OVERDRAFT_DETECTED", "status": "AVAILABLE", "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334", "environment": "production" } ``` --- # API - Enrich | Plaid Docs Enrich  ======= #### API reference for Enrich endpoint  For how-to guidance, see the [Enrich documentation](https://plaid.com/docs/enrich/index.html.md) . | Endpoints | | | --- | --- | | [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) | Send transaction data and retrieve enrichments | \=\*=\*=\*= #### /transactions/enrich  #### Enrich locally-held transaction data  The [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) endpoint enriches raw transaction data generated by your own banking products or retrieved from other non-Plaid sources. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The account type for the requested transactions (either `depository` or `credit`). required, \[object\] An array of transaction objects to be enriched by Plaid. Maximum of 100 transactions per request. required, string A unique ID for the transaction used to help you tie data back to your systems. required, string The raw description of the transaction. If you have location data in available an unstructured format, it may be appended to the `description` field. required, number The absolute value of the transaction (>= 0). When testing Enrich, note that `amount` data should be realistic. Unrealistic or inaccurate `amount` data may result in reduced quality output. Format: `double` required, string The direction of the transaction from the perspective of the account holder: `OUTFLOW` - Includes outgoing transfers, purchases, and fees. (Typically represented as a negative value on checking accounts and debit cards and a positive value on credit cards.) `INFLOW` - Includes incoming transfers, refunds, and income. (Typically represented as a positive value on checking accounts and debit cards and a negative value on credit cards.) Possible values: `INFLOW`, `OUTFLOW` required, string The ISO-4217 currency code of the transaction e.g. USD. object A representation of where a transaction took place. Use this field to pass in structured location information you may have about your transactions. Providing location data is optional but can increase result quality. If you have unstructured location information, it may be appended to the `description` field. string The country where the transaction occurred, formatted as an ISO 3166-1 alpha-2 country code ("US" or "CA"). string The region or state where the transaction occurred, formatted as the official two-letter US state or Canadian province postal code, e.g. "CT" or "QC". string The city where the transaction occurred. string The street address where the transaction occurred. string The postal code where the transaction occurred. string Merchant category codes (MCCs) are four-digit numbers that describe a merchant's primary business activities. string The date the transaction posted, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format. Format: `date` object An optional object to be used with the request. boolean Include `legacy_category` and `legacy_category_id` in the response (in addition to the default `personal_finance_category`). Categories are based on Plaid's legacy taxonomy. For a full list of legacy categories, see [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) . Default: `false` string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` ```bash curl -X POST https://sandbox.plaid.com/transactions/enrich \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "account_type": "depository", "transactions": [ { "id": "6135818adda16500147e7c1d", "description": "PURCHASE WM SUPERCENTER #1700", "amount": 72.10, "direction": "OUTFLOW", "iso_currency_code": "USD", "location": { "city": "Poway", "region": "CA" }, "mcc": "5310", "date_posted": "2022-07-05" }, { "id": "3958434bhde9384bcmeo3401", "description": "DD DOORDASH BURGERKIN 855-123-4567 CA", "amount": 28.34, "direction": "OUTFLOW", "iso_currency_code": "USD" } ] }' ``` ```java List transactionsToEnrich = Arrays.asList( new ClientProvidedTransaction() .id("1") .direction(EnrichTransactionDirection.OUTFLOW) .isoCurrencyCode("USD") .amount(72.10) .location( new ClientProvidedTransactionLocation().city("Poway").region("CA") ) .description("PURCHASE WM SUPERCENTER #1700"), new ClientProvidedTransaction() .id("2") .direction(EnrichTransactionDirection.OUTFLOW) .isoCurrencyCode("USD") .amount(28.34) .description("DD DOORDASH BURGERKIN 855-123-4567 CA") ); TransactionsEnrichRequest transactionsEnrichRequest = new TransactionsEnrichRequest() .accountType("depository").transactions(transactionsToEnrich); Response response = client() .transactionsEnrich(transactionsEnrichRequest) .execute(); List enrichedTransactions = response.body().getEnrichedTransactions(); ``` ```go ctx := context.Background() outflowDirection, _ := plaid.NewEnrichTransactionDirectionFromValue("OUTFLOW") transactionsToEnrich := []plaid.ClientProvidedTransaction{ { Id: "1", Description: "PURCHASE WM SUPERCENTER #1700", Amount: 72.10, IsoCurrencyCode: "USD", Location: &plaid.ClientProvidedTransactionLocation{ City: plaid.PtrString("Poway"), Region: plaid.PtrString("CA"), }, Direction: outflowDirection, }, { Id: "2", Description: "DD DOORDASH BURGERKIN 855-123-4567 CA", Amount: 28.34, IsoCurrencyCode: "USD", Direction: outflowDirection, }, } enrichGetResp, httpResp, err := client.PlaidApi.TransactionsEnrich(ctx).TransactionsEnrichRequest( *plaid.NewTransactionsEnrichRequest( "depository", transactionsToEnrich, ), ).Execute() if err != nil { // handle error } enrichedTransactions := enrichGetResp.GetEnrichedTransactions() ``` ```ruby transactions_to_enrich = [ Plaid::ClientProvidedTransaction.new({ id: "1", description: "PURCHASE WM SUPERCENTER #1700", amount: 72.10, direction: Plaid::EnrichTransactionDirection::OUTFLOW, location: Plaid::ClientProvidedTransactionLocation.new({ city: "Poway", region: "CA", }), iso_currency_code: "USD", }), Plaid::ClientProvidedTransaction.new({ id: "2", description: "DD DOORDASH BURGERKIN 855-123-4567 CA", amount: 28.34, direction: Plaid::EnrichTransactionDirection::OUTFLOW, iso_currency_code: "USD", }), ] transactions_enrich_get_request = Plaid::TransactionsEnrichRequest.new transactions_enrich_get_request.account_type = "depository" transactions_enrich_get_request.transactions = transactions_to_enrich response = client.transactions_enrich(transactions_enrich_get_request) enriched_transactions = response.enriched_transactions ``` ```python transactions_to_enrich = [ ClientProvidedTransaction( id="1", description="PURCHASE WM SUPERCENTER #1700", amount=72.10, iso_currency_code="USD", location=ClientProvidedTransactionLocation( city="Poway", region="CA", ), direction=EnrichTransactionDirection(value="OUTFLOW") ), ClientProvidedTransaction( id="2", description="DD DOORDASH BURGERKIN 855-123-4567 CA", amount=28.34, iso_currency_code="USD", direction=EnrichTransactionDirection(value="OUTFLOW") ), ] enrich_req = TransactionsEnrichRequest( account_type="depository", transactions=transactions_to_enrich ) response = client.transactions_enrich(enrich_req) enriched_transactions = response['enriched_transactions'] ``` ```node const transactionsToEnrich: Array = [ { id: '1', description: 'PURCHASE WM SUPERCENTER #1700', amount: 72.1, iso_currency_code: 'USD', location: { city: 'Poway', region: 'CA', }, direction: EnrichTransactionDirection.Outflow, }, { id: '2', description: 'DD DOORDASH BURGERKIN 855-123-4567 CA', amount: 28.34, iso_currency_code: 'USD', direction: EnrichTransactionDirection.Outflow, }, ]; const request: TransactionsEnrichRequest = { account_type: 'depository', transactions: transactionsToEnrich, }; const response = await client.transactionsEnrich(request); const enrichedTransactions = response.data.enriched_transactions; ``` #### Response fields  \[object\] A list of enriched transactions. string The unique ID for the transaction as provided by you in the request. string The raw description of the transaction. number The absolute value of the transaction (>= 0) Format: `double` string The direction of the transaction from the perspective of the account holder: `OUTFLOW` - Includes outgoing transfers, purchases, and fees. (Typically represented as a negative value on checking accounts and debit cards and a positive value on credit cards.) `INFLOW` - Includes incoming transfers, refunds, and income. (Typically represented as a positive value on checking accounts and debit cards and a negative value on credit cards.) Possible values: `INFLOW`, `OUTFLOW` string The ISO-4217 currency code of the transaction e.g. USD. object A grouping of the Plaid produced transaction enrichment fields. \[object\] The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description. string The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description. nullable, string A unique, stable, Plaid-generated ID that maps to the counterparty. string The counterparty type. `merchant`: a provider of goods or services for purchase `financial_institution`: a financial entity (bank, credit union, BNPL, fintech) `payment_app`: a transfer or P2P app (e.g. Zelle) `marketplace`: a marketplace (e.g DoorDash, Google Play Store) `payment_terminal`: a point-of-sale payment terminal (e.g Square, Toast) `income_source`: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: `merchant`, `financial_institution`, `payment_app`, `marketplace`, `payment_terminal`, `income_source` nullable, string The website associated with the counterparty. nullable, string The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file. nullable, string A description of how confident we are that the provided counterparty is involved in the transaction. `VERY_HIGH`: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. `HIGH`: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. `MEDIUM`: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. `LOW`: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. `UNKNOWN`: We don’t know the confidence level for this counterparty. nullable, string The phone number associated with the counterparty in E. 164 format. If there is a location match (i.e. a street address is returned in the location object), the phone number will be location specific. nullable, object Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe. nullable, object Identifying information for a UK bank account via BACS. nullable, string The BACS account number for the account. nullable, string The BACS sort code for the account. nullable, object Account numbers using the International Bank Account Number and BIC/SWIFT code format. nullable, string International Bank Account Number (IBAN). Min length: `15` Max length: `34` nullable, string Bank identifier code (BIC) for this counterparty. Min length: `8` Max length: `11` nullable, string A unique, stable, Plaid-generated ID that maps to the primary counterparty. deprecated, nullable, string The ID of the legacy category to which this transaction belongs. For a full list of legacy categories, see [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) . We recommend using the `personal_finance_category` for transaction categorization to obtain the best results. deprecated, nullable, \[string\] A hierarchical array of the legacy categories to which this transaction belongs. For a full list of legacy categories, see [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) . We recommend using the `personal_finance_category` for transaction categorization to obtain the best results. object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. nullable, string The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file. nullable, string The name of the primary counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description. string The channel used to make a payment. `online:` transactions that took place online. `in store:` transactions that were made at a physical location. `other:` transactions that relate to banks, e.g. fees or deposits. Possible values: `online`, `in store`, `other` nullable, string The phone number associated with the counterparty in E. 164 format. If there is a location match (i.e. a street address is returned in the location object), the phone number will be location specific. nullable, object Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the [taxonomy CSV file](https://plaid.com/documents/pfc-taxonomy-all.csv) for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the [migration guide](https://plaid.com/docs/transactions/pfc-migration/index.html.md) . string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string A description of how confident we are that the provided categories accurately describe the transaction intent. `VERY_HIGH`: We are more than 98% confident that this category reflects the intent of the transaction. `HIGH`: We are more than 90% confident that this category reflects the intent of the transaction. `MEDIUM`: We are moderately confident that this category reflects the intent of the transaction. `LOW`: This category may reflect the intent, but there may be other categories that are more accurate. `UNKNOWN`: We don’t know the confidence level for this category. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` string The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file. nullable, string The website associated with this transaction. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "enriched_transactions": [ { "id": "6135818adda16500147e7c1d", "description": "PURCHASE WM SUPERCENTER #1700", "amount": 72.1, "direction": "OUTFLOW", "iso_currency_code": "USD", "enrichments": { "counterparties": [ { "name": "Walmart", "type": "merchant", "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "website": "walmart.com", "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM", "confidence_level": "VERY_HIGH", "phone_number": "+18009256278" } ], "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM", "location": { "address": "13425 Community Rd", "city": "Poway", "region": "CA", "postal_code": "92064", "country": "US", "store_number": "1700", "lat": 32.959068, "lon": -117.037666 }, "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "merchant_name": "Walmart", "payment_channel": "in store", "personal_finance_category": { "detailed": "GENERAL_MERCHANDISE_SUPERSTORES", "primary": "GENERAL_MERCHANDISE", "confidence_level": "VERY_HIGH" }, "phone_number": "+18009256278", "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png", "website": "walmart.com" } }, { "id": "3958434bhde9384bcmeo3401", "description": "DD DOORDASH BURGERKIN 855-123-4567 CA", "amount": 28.34, "direction": "OUTFLOW", "iso_currency_code": "USD", "enrichments": { "counterparties": [ { "name": "DoorDash", "type": "marketplace", "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png", "website": "doordash.com", "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm", "confidence_level": "VERY_HIGH", "phone_number": "+18001234567" }, { "name": "Burger King", "type": "merchant", "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png", "website": "burgerking.com", "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1", "confidence_level": "VERY_HIGH", "phone_number": null } ], "location": { "address": null, "city": null, "region": null, "postal_code": null, "country": null, "store_number": null, "lat": null, "lon": null }, "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1", "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png", "merchant_name": "Burger King", "payment_channel": "online", "personal_finance_category": { "detailed": "FOOD_AND_DRINK_FAST_FOOD", "primary": "FOOD_AND_DRINK", "confidence_level": "VERY_HIGH" }, "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png", "phone_number": null, "website": "burgerking.com" } } ], "request_id": "Wvhy9PZHQLV8njG" } ``` --- # API - Identity Verification | Plaid Docs Identity Verification  ====================== #### API reference for Identity Verification endpoints and webhooks  For how-to guidance, see the [Identity Verification documentation](https://plaid.com/docs/identity-verification/index.html.md) . | Endpoints | | | --- | --- | | [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) | Create a new identity verification | | [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) | Retrieve a previously created identity verification | | [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) | Filter and list identity verifications | | [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) | Allow a user to retry an identity verification | | See also | | | --- | --- | | [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) | Retrieve information about a dashboard user | | [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) | List dashboard users | | Webhooks | | | --- | --- | | [STATUS\_UPDATED](https://plaid.com/docs/api/products/identity-verification/index.html.md#status_updated) | The status of an identity verification has been updated | | [STEP\_UPDATED](https://plaid.com/docs/api/products/identity-verification/index.html.md#step_updated) | A step in the identity verification process has been completed | | [RETRIED](https://plaid.com/docs/api/products/identity-verification/index.html.md#retried) | An identity verification has been retried | ### Endpoints  \=\*=\*=\*= #### /identity\_verification/create  #### Create a new Identity Verification  Create a new Identity Verification for the user specified by the `client_user_id` and/or `user_id` field. At least one of these two fields must be provided. The requirements and behavior of the verification are determined by the `template_id` provided. If `user_id` is provided, there must be an associated user otherwise an error will be returned. If you don't know whether an active Identity Verification exists for a given `client_user_id` and/or `user_id`, you can specify `"is_idempotent": true` in the request body. With idempotency enabled, a new Identity Verification will only be created if one does not already exist for the associated `client_user_id` and/or `user_id`, and `template_id`. If an Identity Verification is found, it will be returned unmodified with a `200 OK` HTTP status code. If `user_id` is not provided, you can also use this endpoint to supply information you already have collected about the user; if any of these fields are specified, the screens prompting the user to enter them will be skipped during the Link flow. If `user_id` is provided, user information can not be included in the request body. Please use the [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) endpoint to update user data instead. #### Request fields  string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string Unique user identifier, created by calling `/user/create`. Either a `user_id` or the `client_user_id` must be provided. The `user_id` may only be used instead of the `client_user_id` if you were not a pre-existing user of `/user/create` as of December 10, 2025; for more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . If both this field and a `client_user_id` are present in a request, the `user_id` must have been created from the provided `client_user_id`. required, boolean A flag specifying whether you would like Plaid to expose a shareable URL for the verification being created. required, string ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive. required, boolean A flag specifying whether the end user has already agreed to a privacy policy specifying that their data will be shared with Plaid for verification purposes. If `gave_consent` is set to `true`, the `accept_tos` step will be marked as `skipped` and the end user's session will start at the next step requirement. Default: `false` object User information collected outside of Link, most likely via your own onboarding process. Each of the following identity fields are optional: `email_address` `phone_number` `date_of_birth` `name` `address` `id_number` Specifically, these fields are optional in that they can either be fully provided (satisfying every required field in their subschema) or omitted from the request entirely by not providing the key or value. Providing these fields via the API will result in Link skipping the data collection process for the associated user. All verification steps enabled in the associated Identity Verification Template will still be run. Verification steps will either be run immediately, or once the user completes the `accept_tos` step, depending on the value provided to the `gave_consent` field. If you are not using the shareable URL feature, you can optionally provide these fields via `/link/token/create` instead; both `/identity_verification/create` and `/link/token/create` are valid ways to provide this information. Note that if you provide a non-`null` user data object via `/identity_verification/create`, any user data fields entered via `/link/token/create` for the same `client_user_id` will be ignored when prefilling Link. string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` string A valid phone number in E.164 format. string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` object You can use this field to pre-populate the user's legal name; if it is provided here, they will not be prompted to enter their name in the identity verification attempt. required, string A string with at least one non-whitespace character, with a max length of 100 characters. required, string A string with at least one non-whitespace character, with a max length of 100 characters. object Home address for the user. Supported values are: not provided, address with only country code or full address. For more context on this field, see [Input Validation by Country](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#input-validation-by-country) . string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. required, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. object ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be `null`. Otherwise, both fields are guaranteed to be filled. required, string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . required, string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` deprecated, string Specifying `user.client_user_id` is deprecated. Please provide `client_user_id` at the root level instead. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. boolean An optional flag specifying how you would like Plaid to handle attempts to create an Identity Verification when an Identity Verification already exists for the provided `client_user_id` and `template_id`. If idempotency is enabled, Plaid will return the existing Identity Verification. If idempotency is disabled, Plaid will reject the request with a `400 Bad Request` status code if an Identity Verification already exists for the supplied `client_user_id` and `template_id`. ```node const request: IdentityVerificationCreateRequest = { client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', is_shareable: true, template_id: 'idvtmp_52xR9LKo77r1Np', gave_consent: true, user: { email_address: 'acharleston@email.com', phone_number: '+12345678909', date_of_birth: '1975-01-18', name: { given_name: 'Anna', family_name: 'Charleston', }, address: { street: '100 Market Street', street2: 'Apt 1A', city: 'San Francisco', region: 'CA', postal_code: '94103', country: 'US', }, id_number: { value: '123456789', type: 'us_ssn', }, }, }; try { const response = await client.identityVerificationCreate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/identity_verification/create \ -H 'Content-Type: application/json' \ -d '{ "client_user_id": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "is_shareable": true, "template_id": "idvtmp_52xR9LKo77r1Np", "gave_consent": true, "user": { "email_address": "acharleston@email.com", "phone_number": "+12345678909", "date_of_birth": "1975-01-18", "name": { "given_name": "Anna", "family_name": "Charleston" }, "address": { "street": "100 Market Street", "street2": "Apt 1A", "city": "San Francisco", "region": "CA", "postal_code": "94103", "country": "US" }, "id_number": { "value": "123456789", "type": "us_ssn" } } }' ``` ```ruby require 'date' request = Plaid::IdentityVerificationCreateRequest.new( { client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', is_shareable: true, template_id: 'idvtmp_52xR9LKo77r1Np', gave_consent: true, user: Plaid::IdentityVerificationCreateRequestUser.new( { email_address: 'acharleston@email.com', phone_number: '+12345678909', date_of_birth: Date.new(1975, 1, 18), name: Plaid::IdentityVerificationRequestUserName.new( { given_name: 'Anna', family_name: 'Charleston' } ), address: Plaid::UserAddress.new( { street: '100 Market Street', street2: 'Apt 1A', city: 'San Francisco', region: 'CA', postal_code: '94103', country: 'US' } ), id_number: Plaid::UserIDNumber.new( { value: '123456789', type: Plaid::IDNumberType::US_SSN } ) } ) } ) response = client.identity_verification_create(request) ``` ```java import java.time.LocalDate; LocalDate dob = LocalDate.parse("1975-01-18"); IdentityVerificationRequestUserName name = new IdentityVerificationRequestUserName() .givenName("Anna") .familyName("Charleston"); UserAddress address = new UserAddress() .street("100 Market Street") .street2("Apt 1A") .city("San Francisco") .region("CA") .postalCode("94103") .country("US"); IDNumberType type = IDNumberType.US_SSN; UserIDNumber idNumber = new UserIDNumber() .value("123456789") .type(type); IdentityVerificationCreateRequestUser user = new IdentityVerificationCreateRequestUser() .emailAddress("acharleston@email.com") .phoneNumber("+12345678909") .dateOfBirth(dob) .name(name) .address(address) .idNumber(idNumber); IdentityVerificationCreateRequest request = new IdentityVerificationCreateRequest() .clientUserId("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d") .isShareable(true) .templateId("idvtmp_52xR9LKo77r1Np") .gaveConsent(true) .user(user); Response response = client() .identityVerificationCreate(request) .execute(); ``` ```python from datetime import date request = IdentityVerificationCreateRequest( client_user_id=ClientUserID('user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d'), is_shareable=True, template_id='idvtmp_52xR9LKo77r1Np', gave_consent=True, user=IdentityVerificationCreateRequestUser( email_address='acharleston@email.com', phone_number='+12345678909', date_of_birth=date(1975, 1, 18), name=IdentityVerificationRequestUserName( given_name='Anna', family_name='Charleston' ), address=UserAddress( street='100 Market Street', street2='Apt 1A', city='San Francisco', region='CA', postal_code='94103', country=GenericCountryCode('US') ), id_number=UserIDNumber( value='123456789', type=IDNumberType('us_ssn') ) ) ) response = client.identity_verification_create(request) ``` ```go user := plaid.NewIdentityVerificationCreateRequestUser() user.SetEmailAddress("acharleston@email.com") user.SetPhoneNumber("+12345678909") user.SetDateOfBirth("1975-01-18") user.SetName( *plaid.NewIdentityVerificationRequestUserName( "Anna", "Charleston", ), ) user.SetAddress( *plaid.NewUserAddress( "100 Market Street", "San Francisco", "CA", "94103", "US", ), ) user.SetIdNumber( *plaid.NewUserIDNumber( "123456789", plaid.IDNUMBERTYPE_US_SSN, ), ) request := plaid.NewIdentityVerificationCreateRequest( true, "idv_52xR9LKo77r1Np", true, ) request.SetClientUserId("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d") request.SetUser(*user) response, _, err := client.PlaidApi. IdentityVerificationCreate(ctx). IdentityVerificationCreateRequest(*request). Execute() ``` #### Response fields  string ID of the associated Identity Verification attempt. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt. nullable, string A shareable URL that can be sent directly to the user to complete verification object The resource ID and version number of the template configuring the behavior of a given Identity Verification. string ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive. integer Version of the associated Identity Verification template. object The identity data that was either collected from the user or provided via API in order to perform an Identity Verification. nullable, string A valid phone number in E.164 format. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string An IPv4 or IPV6 address. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, object The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. nullable, object Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code nullable, string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. nullable, string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. nullable, string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, object ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be `null`. Otherwise, both fields are guaranteed to be filled. string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` string The status of this Identity Verification attempt. `active` - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed. `success` - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template `failed` - The user failed one or more steps in the session and was told to contact support. `expired` - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future. `canceled` - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed. `pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. Possible values: `active`, `success`, `failed`, `expired`, `canceled`, `pending_review` object Each step will be one of the following values: `active` - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as `active` at any given point. `success` - The Identity Verification attempt has completed this step. `failed` - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session. `waiting_for_prerequisite` - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback. `not_applicable` - This step will not be run for this session. `skipped` - The retry instructions that created this Identity Verification attempt specified that this step should be skipped. `expired` - This step had not yet been completed when the Identity Verification attempt as a whole expired. `canceled` - The Identity Verification attempt was canceled before the user completed this step. `pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. `manually_approved` - The step was manually overridden to pass by a team member in the dashboard. `manually_rejected` - The step was manually overridden to fail by a team member in the dashboard. string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` nullable, object Data, images, analysis, and results from the `documentary_verification` step. This field will be `null` unless `steps.documentary_verification` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `documentary_verification` step. This field will always have the same value as `steps.documentary_verification`. \[object\] An array of documents submitted to the `documentary_verification` step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type. Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within `documents`. If the overall `documentary_verification` is `failed`, the user has exhausted their retry attempts. string An outcome status for this specific document submission. Distinct from the overall `documentary_verification.status` that summarizes the verification outcome from one or more documents. Possible values: `success`, `failed`, `manually_approved` integer The `attempt` field begins with 1 and increments with each subsequent document upload. object URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the `GET` request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires. nullable, string Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document. nullable, string Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected. nullable, string Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document. nullable, string Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected. nullable, string Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo. nullable, object Data extracted from a user-submitted document. nullable, string Alpha-numeric ID number extracted via OCR from the user's document image. string The type of identity document detected in the images provided. Will always be one of the following values: `drivers_license` - A driver's license issued by the associated country, establishing identity without any guarantee as to citizenship, and granting driving privileges `id_card` - A general national identification card, distinct from driver's licenses as it only establishes identity `passport` - A travel passport issued by the associated country for one of its citizens `residence_permit_card` - An identity document issued by the associated country permitting a foreign citizen to _temporarily_ reside there `resident_card` - An identity document issued by the associated country permitting a foreign citizen to _permanently_ reside there `visa` - An identity document issued by the associated country permitting a foreign citizen entry for a short duration and for a specific purpose, typically no longer than 6 months Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say `passport` Possible values: `drivers_license`, `id_card`, `passport`, `residence_permit_card`, `resident_card`, `visa` nullable, string The expiration date of the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string The issue date of the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, object The address extracted from the document. The address must at least contain the following fields to be a valid address: `street`, `city`, `country`. If any are missing or unable to be extracted, the address will be null. `region`, and `postal_code` may be null based on the addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document. string The full street address extracted from the document. string City extracted from the document. nullable, string A subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc. For a full list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they can be inferred from the `country` field. nullable, string The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form. nullable, object The individual's name extracted from the document. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. object High level descriptions of how the associated document was processed. If a document fails verification, the details in the `analysis` object should help clarify why the document was rejected. string High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction. For example, most identity documents have formatting rules like the following: The image of the person's face must have a certain contrast in order to highlight skin tone The subject in the document's image must remove eye glasses and pose in a certain way The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules Security features like watermarks and background patterns must be present So a `match` status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A high level description of the quality of the image the user submitted. For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks. Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality. Possible values: `high`, `medium`, `low` nullable, object Analysis of the data extracted from the submitted document. string A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A description of whether the associated document was expired when the verification was performed. Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be `no_data`. Possible values: `not_expired`, `expired`, `no_data` string A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid. Note: You can configure whether a `no_match` on `issuing_country` fails the `documentary_verification` by editing your Plaid Template. Possible values: `match`, `no_match` nullable, object Analyzed AAMVA data for the associated hit. Note: This field is only available for U.S. driver's licenses issued by participating states. boolean The overall outcome of checking the associated hit against the issuing state database. string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, object Additional information for the `selfie_check` step. This field will be `null` unless `steps.selfie_check` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `selfie_check` step. This field will always have the same value as `steps.selfie_check`. Possible values: `success`, `failed` \[object\] An array of selfies submitted to the `selfie_check` step. Each entry represents one user submission. string An outcome status for this specific selfie. Distinct from the overall `selfie_check.status` that summarizes the verification outcome from one or more selfies. Possible values: `success`, `failed` integer The `attempt` field begins with 1 and increments with each subsequent selfie upload. object The image or video capture of a selfie. Only one of image or video URL will be populated per selfie. nullable, string Temporary URL for downloading an image selfie capture. nullable, string Temporary URL for downloading a video selfie capture. object High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the `analysis` object should help clarify why the selfie was rejected. string Information about the comparison between the selfie and the document (if documentary verification also ran). Possible values: `match`, `no_match`, `no_input` string Assessment of whether the selfie capture is of a real human being, as opposed to a picture of a human on a screen, a picture of a paper cut out, someone wearing a mask, or a deepfake. Possible values: `success`, `failed` nullable, object Additional information for the `kyc_check` (Data Source Verification) step. This field will be `null` unless `steps.kyc_check` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `kyc_check` step. This field will always have the same value as `steps.kyc_check`. object Result summary object specifying how the `address` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string Field describing whether the associated address is a post office box. Will be `yes` when a P.O. box is detected, `no` when Plaid confirmed the address is not a P.O. box, and `no_data` when Plaid was not able to determine if the address is a P.O. box. Possible values: `yes`, `no`, `no_data` string Field describing whether the associated address is being used for commercial or residential purposes. Note: This value will be `no_data` when Plaid does not have sufficient data to determine the address's use. Possible values: `residential`, `commercial`, `no_data` object Result summary object specifying how the `name` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `date_of_birth` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `id_number` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `phone` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` nullable, object Additional information for the `risk_check` step. string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` nullable, object Result summary object specifying values for `behavior` attributes of risk check, when available. string Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session. `genuine` indicates the user has high familiarity with the data they are providing, and that fraud is unlikely. `neutral` indicates some signals are present in between `risky` and `genuine`, but there are not enough clear signals to determine an outcome. `risky` indicates the user has low familiarity with the data they are providing, and that fraud is likely. `no_data` indicates there is not sufficient information to give an accurate signal. Possible values: `genuine`, `neutral`, `risky`, `no_data` string Field describing the outcome of a fraud ring behavior risk check. `yes` indicates that fraud ring activity was detected. `no` indicates that fraud ring activity was not detected. `no_data` indicates there was not enough information available to give an accurate signal. Possible values: `yes`, `no`, `no_data` string Field describing the outcome of a bot detection behavior risk check. `yes` indicates that automated activity was detected. `no` indicates that automated activity was not detected. `no_data` indicates there was not enough information available to give an accurate signal. Possible values: `yes`, `no`, `no_data` nullable, object Result summary object specifying values for `email` attributes of risk check. string SMTP-MX check to confirm the email address exists if known. Possible values: `yes`, `no`, `no_data` nullable, integer Count of all known breaches of this email address if known. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known. Possible values: `yes`, `no`, `no_data` string Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable. Possible values: `yes`, `no`, `no_data` string Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details. Possible values: `yes`, `no`, `no_data` string Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain. Possible values: `yes`, `no`, `no_data` \[string\] A list of online services where this email address has been detected to have accounts or other activity. Possible values: `aboutme`, `adobe`, `adult_sites`, `airbnb`, `altbalaji`, `amazon`, `apple`, `archiveorg`, `atlassian`, `bitmoji`, `bodybuilding`, `booking`, `bukalapak`, `codecademy`, `deliveroo`, `diigo`, `discord`, `disneyplus`, `duolingo`, `ebay`, `envato`, `eventbrite`, `evernote`, `facebook`, `firefox`, `flickr`, `flipkart`, `foursquare`, `freelancer`, `gaana`, `giphy`, `github`, `google`, `gravatar`, `hubspot`, `imgur`, `instagram`, `jdid`, `kakao`, `kommo`, `komoot`, `lastfm`, `lazada`, `line`, `linkedin`, `mailru`, `microsoft`, `myspace`, `netflix`, `nike`, `ok`, `patreon`, `pinterest`, `plurk`, `quora`, `qzone`, `rambler`, `rappi`, `replit`, `samsung`, `seoclerks`, `shopclues`, `skype`, `snapchat`, `snapdeal`, `soundcloud`, `spotify`, `starz`, `strava`, `taringa`, `telegram`, `tiki`, `tokopedia`, `treehouse`, `tumblr`, `twitter`, `venmo`, `viber`, `vimeo`, `vivino`, `vkontakte`, `wattpad`, `weibo`, `whatsapp`, `wordpress`, `xing`, `yahoo`, `yandex`, `zalo`, `zoho` nullable, object Result summary object specifying values for `phone` attributes of risk check. \[string\] A list of online services where this phone number has been detected to have accounts or other activity. Possible values: `aboutme`, `adobe`, `adult_sites`, `airbnb`, `altbalaji`, `amazon`, `apple`, `archiveorg`, `atlassian`, `bitmoji`, `bodybuilding`, `booking`, `bukalapak`, `codecademy`, `deliveroo`, `diigo`, `discord`, `disneyplus`, `duolingo`, `ebay`, `envato`, `eventbrite`, `evernote`, `facebook`, `firefox`, `flickr`, `flipkart`, `foursquare`, `freelancer`, `gaana`, `giphy`, `github`, `google`, `gravatar`, `hubspot`, `imgur`, `instagram`, `jdid`, `kakao`, `kommo`, `komoot`, `lastfm`, `lazada`, `line`, `linkedin`, `mailru`, `microsoft`, `myspace`, `netflix`, `nike`, `ok`, `patreon`, `pinterest`, `plurk`, `quora`, `qzone`, `rambler`, `rappi`, `replit`, `samsung`, `seoclerks`, `shopclues`, `skype`, `snapchat`, `snapdeal`, `soundcloud`, `spotify`, `starz`, `strava`, `taringa`, `telegram`, `tiki`, `tokopedia`, `treehouse`, `tumblr`, `twitter`, `venmo`, `viber`, `vimeo`, `vivino`, `vkontakte`, `wattpad`, `weibo`, `whatsapp`, `wordpress`, `xing`, `yahoo`, `yandex`, `zalo`, `zoho` \[object\] Array of result summary objects specifying values for `device` attributes of risk check. nullable, string An enum indicating whether a network proxy is present and if so what type it is. `none_detected` indicates the user is not on a detectable proxy network. `tor` indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). `vpn` indicates the user is on a VPN (Virtual Private Network) `web_proxy` indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. `public_proxy` indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance. Possible values: `none_detected`, `tor`, `vpn`, `web_proxy`, `public_proxy` nullable, integer Count of spam lists the IP address is associated with if known. nullable, string UTC offset of the timezone associated with the IP address. nullable, object Result summary object capturing abuse signals related to `identity abuse`, e.g. stolen and synthetic identity fraud. These attributes are only available for US identities and some signals may not be available depending on what information was collected. nullable, object Field containing the data used in determining the outcome of the synthetic identity risk check. Contains the following fields: `score` - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity. integer A score from 0 to 100 indicating the likelihood that the user is a synthetic identity. nullable, object Field containing the data used in determining the outcome of the stolen identity risk check. Contains the following fields: `score` - A score from 0 to 100 indicating the likelihood that the user is a stolen identity. integer A score from 0 to 100 indicating the likelihood that the user is a stolen identity. \[object\] The attributes related to the facial duplicates captured in risk check. string ID of the associated Identity Verification attempt. integer Similarity score of the match. Ranges from 0 to 100. boolean Whether this match occurred after the session was complete. For example, this would be `true` if a later session ended up matching this one. nullable, integer The trust index score for the `risk_check` step. nullable, object Additional information for the `verify_sms` step. string The outcome status for the associated Identity Verification attempt's `verify_sms` step. This field will always have the same value as `steps.verify_sms`. Possible values: `success`, `failed` \[object\] An array where each entry represents a verification attempt for the `verify_sms` step. Each entry represents one user-submitted phone number. Phone number edits, and in some cases error handling due to edge cases like rate limiting, may generate additional verifications. string The outcome status for the individual SMS verification. Possible values: `pending`, `success`, `failed`, `canceled` integer The attempt field begins with 1 and increments with each subsequent SMS verification. nullable, string A phone number in E.164 format. integer The number of delivery attempts made within the verification to send the SMS code to the user. Each delivery attempt represents the user taking action from the front end UI to request creation and delivery of a new SMS verification code, or to resend an existing SMS verification code. There is a limit of 3 delivery attempts per verification. integer The number of attempts made by the user within the verification to verify the SMS code by entering it into the front end UI. There is a limit of 3 solve attempts per verification. nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string ID of the associated screening. nullable, string ID of the associated Beacon User. nullable, string Unique user identifier, created by calling `/user/create`. Either a `user_id` or the `client_user_id` must be provided. The `user_id` may only be used instead of the `client_user_id` if you were not a pre-existing user of `/user/create` as of December 10, 2025; for more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . If both this field and a `client_user_id` are present in a request, the `user_id` must have been created from the provided `client_user_id`. nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, object Information about a Protect event including Trust Index score and fraud attributes. string The event ID. string The timestamp of the event, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2017-09-14T14:42:19.350Z"` Format: `date-time` nullable, object Represents a calculated Trust Index Score. integer The overall trust index score. string The versioned name of the Trust Index model used for scoring. nullable, object Contains sub-score metadata. nullable, object Represents Trust Index Subscore. integer The subscore score. nullable, object Represents Trust Index Subscore. integer The subscore score. nullable, object Event fraud attributes as an arbitrary set of key-value pairs. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "idv_52xR9LKo77r1Np", "client_user_id": "your-db-id-3b24110", "created_at": "2020-07-24T03:26:02Z", "completed_at": "2020-07-24T03:26:02Z", "previous_attempt_id": "idv_42cF1MNo42r9Xj", "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f", "template": { "id": "idvtmp_4FrXJvfQU3zGUR", "version": 2 }, "user": { "phone_number": "+12345678909", "date_of_birth": "1990-05-29", "ip_address": "192.0.2.42", "email_address": "user@example.com", "name": { "given_name": "Leslie", "family_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "id_number": { "value": "123456789", "type": "us_ssn" } }, "status": "success", "steps": { "accept_tos": "success", "verify_sms": "success", "kyc_check": "success", "documentary_verification": "success", "selfie_check": "success", "watchlist_screening": "success", "risk_check": "success" }, "documentary_verification": { "status": "success", "documents": [ { "status": "success", "attempt": 1, "images": { "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg", "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg", "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg", "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg", "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg" }, "extracted_data": { "id_number": "AB123456", "category": "drivers_license", "expiration_date": "2030-05-29", "issue_date": "2020-05-29", "issuing_country": "US", "issuing_region": "IN", "date_of_birth": "1990-05-29", "address": { "street": "123 Main St. Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "name": { "given_name": "Leslie", "family_name": "Knope" } }, "analysis": { "authenticity": "match", "image_quality": "high", "extracted_data": { "name": "match", "date_of_birth": "match", "expiration_date": "not_expired", "issuing_country": "match" }, "aamva_verification": { "is_verified": true, "id_number": "match", "id_issue_date": "match", "id_expiration_date": "match", "street": "match", "city": "match", "postal_code": "match", "date_of_birth": "match", "gender": "match", "height": "match", "eye_color": "match", "first_name": "match", "middle_name": "match", "last_name": "match" } }, "redacted_at": "2020-07-24T03:26:02Z" } ] }, "selfie_check": { "status": "success", "selfies": [ { "status": "success", "attempt": 1, "capture": { "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg", "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm" }, "analysis": { "document_comparison": "match", "liveness_check": "success" } } ] }, "kyc_check": { "status": "success", "address": { "summary": "match", "po_box": "yes", "type": "residential" }, "name": { "summary": "match" }, "date_of_birth": { "summary": "match" }, "id_number": { "summary": "match" }, "phone_number": { "summary": "match", "area_code": "match" } }, "risk_check": { "status": "success", "behavior": { "user_interactions": "risky", "fraud_ring_detected": "yes", "bot_detected": "yes" }, "email": { "is_deliverable": "yes", "breach_count": 1, "first_breached_at": "1990-05-29", "last_breached_at": "1990-05-29", "domain_registered_at": "1990-05-29", "domain_is_free_provider": "yes", "domain_is_custom": "yes", "domain_is_disposable": "yes", "top_level_domain_is_suspicious": "yes", "linked_services": [ "apple" ] }, "phone": { "linked_services": [ "apple" ] }, "devices": [ { "ip_proxy_type": "none_detected", "ip_spam_list_count": 1, "ip_timezone_offset": "+06:00:00" } ], "identity_abuse_signals": { "synthetic_identity": { "score": 0 }, "stolen_identity": { "score": 0 } }, "facial_duplicates": [ { "id": "idv_52xR9LKo77r1Np", "similarity": 95, "matched_after_completed": true } ], "trust_index_score": 86 }, "verify_sms": { "status": "success", "verifications": [ { "status": "success", "attempt": 1, "phone_number": "+12345678909", "delivery_attempt_count": 1, "solve_attempt_count": 1, "initially_sent_at": "2020-07-24T03:26:02Z", "last_sent_at": "2020-07-24T03:26:02Z", "redacted_at": "2020-07-24T03:26:02Z" } ] }, "watchlist_screening_id": "scr_52xR9LKo77r1Np", "beacon_user_id": "becusr_42cF1MNo42r9Xj", "user_id": "usr_dddAs9ewdcDQQQ", "redacted_at": "2020-07-24T03:26:02Z", "latest_scored_protect_event": { "event_id": "ptevt_7AJYTMFxRUgJ", "timestamp": "2020-07-24T03:26:02Z", "trust_index": { "score": 86, "model": "trust_index.2.0.0", "subscores": { "device_and_connection": { "score": 87 }, "bank_account_insights": { "score": 85 } } }, "fraud_attributes": { "fraud_attributes": { "link_session.linked_bank_accounts.user_pi_matches_owners": true, "link_session.linked_bank_accounts.connected_apps.days_since_first_connection": 582, "session.challenged_with_mfa": false, "user.bank_accounts.num_of_frozen_or_restricted_accounts": 0, "user.linked_bank_accounts.num_family_names": 1, "user.linked_bank_accounts.num_of_connected_banks": 1, "user.link_sessions.days_since_first_link_session": 150, "user.pi.email.history_yrs": 7.03, "user.pi.email.num_social_networks_linked": 12, "user.pi.ssn.user_likely_has_better_ssn": false } } }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /identity\_verification/get  #### Retrieve Identity Verification  Retrieve a previously created Identity Verification. #### Request fields  required, string ID of the associated Identity Verification attempt. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. ```node const request: IdentityVerificationGetRequest = { identity_verification_id: 'idv_52xR9LKo77r1Np', }; try { const response = await plaidClient.identityVerificationGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/identity_verification/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "identity_verification_id": "idv_52xR9LKo77r1Np" }' ``` ```ruby request = Plaid::IdentityVerificationGetRequest.new({ identity_verification_id: 'idv_52xR9LKo77r1Np' }) response = client.identity_verification_get(request) ``` ```java IdentityVerificationGetRequest request = new IdentityVerificationGetRequest() .identityVerificationId("idv_52xR9LKo77r1Np"); Response response = client() .identityVerificationGet(request) .execute(); ``` ```python request = IdentityVerificationGetRequest(identity_verification_id='idv_52xR9LKo77r1Np') response = client.identity_verification_get(request) ``` ```go request := plaid.NewIdentityVerificationGetRequest( "idv_52xR9LKo77r1Np", ) response, _, err := client.PlaidApi. IdentityVerificationGet(ctx). IdentityVerificationGetRequest(*request). Execute() ``` #### Response fields  string ID of the associated Identity Verification attempt. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt. nullable, string A shareable URL that can be sent directly to the user to complete verification object The resource ID and version number of the template configuring the behavior of a given Identity Verification. string ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive. integer Version of the associated Identity Verification template. object The identity data that was either collected from the user or provided via API in order to perform an Identity Verification. nullable, string A valid phone number in E.164 format. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string An IPv4 or IPV6 address. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, object The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. nullable, object Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code nullable, string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. nullable, string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. nullable, string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, object ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be `null`. Otherwise, both fields are guaranteed to be filled. string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` string The status of this Identity Verification attempt. `active` - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed. `success` - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template `failed` - The user failed one or more steps in the session and was told to contact support. `expired` - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future. `canceled` - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed. `pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. Possible values: `active`, `success`, `failed`, `expired`, `canceled`, `pending_review` object Each step will be one of the following values: `active` - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as `active` at any given point. `success` - The Identity Verification attempt has completed this step. `failed` - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session. `waiting_for_prerequisite` - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback. `not_applicable` - This step will not be run for this session. `skipped` - The retry instructions that created this Identity Verification attempt specified that this step should be skipped. `expired` - This step had not yet been completed when the Identity Verification attempt as a whole expired. `canceled` - The Identity Verification attempt was canceled before the user completed this step. `pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. `manually_approved` - The step was manually overridden to pass by a team member in the dashboard. `manually_rejected` - The step was manually overridden to fail by a team member in the dashboard. string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` nullable, object Data, images, analysis, and results from the `documentary_verification` step. This field will be `null` unless `steps.documentary_verification` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `documentary_verification` step. This field will always have the same value as `steps.documentary_verification`. \[object\] An array of documents submitted to the `documentary_verification` step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type. Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within `documents`. If the overall `documentary_verification` is `failed`, the user has exhausted their retry attempts. string An outcome status for this specific document submission. Distinct from the overall `documentary_verification.status` that summarizes the verification outcome from one or more documents. Possible values: `success`, `failed`, `manually_approved` integer The `attempt` field begins with 1 and increments with each subsequent document upload. object URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the `GET` request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires. nullable, string Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document. nullable, string Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected. nullable, string Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document. nullable, string Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected. nullable, string Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo. nullable, object Data extracted from a user-submitted document. nullable, string Alpha-numeric ID number extracted via OCR from the user's document image. string The type of identity document detected in the images provided. Will always be one of the following values: `drivers_license` - A driver's license issued by the associated country, establishing identity without any guarantee as to citizenship, and granting driving privileges `id_card` - A general national identification card, distinct from driver's licenses as it only establishes identity `passport` - A travel passport issued by the associated country for one of its citizens `residence_permit_card` - An identity document issued by the associated country permitting a foreign citizen to _temporarily_ reside there `resident_card` - An identity document issued by the associated country permitting a foreign citizen to _permanently_ reside there `visa` - An identity document issued by the associated country permitting a foreign citizen entry for a short duration and for a specific purpose, typically no longer than 6 months Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say `passport` Possible values: `drivers_license`, `id_card`, `passport`, `residence_permit_card`, `resident_card`, `visa` nullable, string The expiration date of the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string The issue date of the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, object The address extracted from the document. The address must at least contain the following fields to be a valid address: `street`, `city`, `country`. If any are missing or unable to be extracted, the address will be null. `region`, and `postal_code` may be null based on the addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document. string The full street address extracted from the document. string City extracted from the document. nullable, string A subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc. For a full list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they can be inferred from the `country` field. nullable, string The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form. nullable, object The individual's name extracted from the document. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. object High level descriptions of how the associated document was processed. If a document fails verification, the details in the `analysis` object should help clarify why the document was rejected. string High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction. For example, most identity documents have formatting rules like the following: The image of the person's face must have a certain contrast in order to highlight skin tone The subject in the document's image must remove eye glasses and pose in a certain way The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules Security features like watermarks and background patterns must be present So a `match` status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A high level description of the quality of the image the user submitted. For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks. Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality. Possible values: `high`, `medium`, `low` nullable, object Analysis of the data extracted from the submitted document. string A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A description of whether the associated document was expired when the verification was performed. Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be `no_data`. Possible values: `not_expired`, `expired`, `no_data` string A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid. Note: You can configure whether a `no_match` on `issuing_country` fails the `documentary_verification` by editing your Plaid Template. Possible values: `match`, `no_match` nullable, object Analyzed AAMVA data for the associated hit. Note: This field is only available for U.S. driver's licenses issued by participating states. boolean The overall outcome of checking the associated hit against the issuing state database. string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, object Additional information for the `selfie_check` step. This field will be `null` unless `steps.selfie_check` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `selfie_check` step. This field will always have the same value as `steps.selfie_check`. Possible values: `success`, `failed` \[object\] An array of selfies submitted to the `selfie_check` step. Each entry represents one user submission. string An outcome status for this specific selfie. Distinct from the overall `selfie_check.status` that summarizes the verification outcome from one or more selfies. Possible values: `success`, `failed` integer The `attempt` field begins with 1 and increments with each subsequent selfie upload. object The image or video capture of a selfie. Only one of image or video URL will be populated per selfie. nullable, string Temporary URL for downloading an image selfie capture. nullable, string Temporary URL for downloading a video selfie capture. object High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the `analysis` object should help clarify why the selfie was rejected. string Information about the comparison between the selfie and the document (if documentary verification also ran). Possible values: `match`, `no_match`, `no_input` string Assessment of whether the selfie capture is of a real human being, as opposed to a picture of a human on a screen, a picture of a paper cut out, someone wearing a mask, or a deepfake. Possible values: `success`, `failed` nullable, object Additional information for the `kyc_check` (Data Source Verification) step. This field will be `null` unless `steps.kyc_check` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `kyc_check` step. This field will always have the same value as `steps.kyc_check`. object Result summary object specifying how the `address` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string Field describing whether the associated address is a post office box. Will be `yes` when a P.O. box is detected, `no` when Plaid confirmed the address is not a P.O. box, and `no_data` when Plaid was not able to determine if the address is a P.O. box. Possible values: `yes`, `no`, `no_data` string Field describing whether the associated address is being used for commercial or residential purposes. Note: This value will be `no_data` when Plaid does not have sufficient data to determine the address's use. Possible values: `residential`, `commercial`, `no_data` object Result summary object specifying how the `name` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `date_of_birth` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `id_number` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `phone` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` nullable, object Additional information for the `risk_check` step. string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` nullable, object Result summary object specifying values for `behavior` attributes of risk check, when available. string Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session. `genuine` indicates the user has high familiarity with the data they are providing, and that fraud is unlikely. `neutral` indicates some signals are present in between `risky` and `genuine`, but there are not enough clear signals to determine an outcome. `risky` indicates the user has low familiarity with the data they are providing, and that fraud is likely. `no_data` indicates there is not sufficient information to give an accurate signal. Possible values: `genuine`, `neutral`, `risky`, `no_data` string Field describing the outcome of a fraud ring behavior risk check. `yes` indicates that fraud ring activity was detected. `no` indicates that fraud ring activity was not detected. `no_data` indicates there was not enough information available to give an accurate signal. Possible values: `yes`, `no`, `no_data` string Field describing the outcome of a bot detection behavior risk check. `yes` indicates that automated activity was detected. `no` indicates that automated activity was not detected. `no_data` indicates there was not enough information available to give an accurate signal. Possible values: `yes`, `no`, `no_data` nullable, object Result summary object specifying values for `email` attributes of risk check. string SMTP-MX check to confirm the email address exists if known. Possible values: `yes`, `no`, `no_data` nullable, integer Count of all known breaches of this email address if known. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known. Possible values: `yes`, `no`, `no_data` string Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable. Possible values: `yes`, `no`, `no_data` string Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details. Possible values: `yes`, `no`, `no_data` string Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain. Possible values: `yes`, `no`, `no_data` \[string\] A list of online services where this email address has been detected to have accounts or other activity. Possible values: `aboutme`, `adobe`, `adult_sites`, `airbnb`, `altbalaji`, `amazon`, `apple`, `archiveorg`, `atlassian`, `bitmoji`, `bodybuilding`, `booking`, `bukalapak`, `codecademy`, `deliveroo`, `diigo`, `discord`, `disneyplus`, `duolingo`, `ebay`, `envato`, `eventbrite`, `evernote`, `facebook`, `firefox`, `flickr`, `flipkart`, `foursquare`, `freelancer`, `gaana`, `giphy`, `github`, `google`, `gravatar`, `hubspot`, `imgur`, `instagram`, `jdid`, `kakao`, `kommo`, `komoot`, `lastfm`, `lazada`, `line`, `linkedin`, `mailru`, `microsoft`, `myspace`, `netflix`, `nike`, `ok`, `patreon`, `pinterest`, `plurk`, `quora`, `qzone`, `rambler`, `rappi`, `replit`, `samsung`, `seoclerks`, `shopclues`, `skype`, `snapchat`, `snapdeal`, `soundcloud`, `spotify`, `starz`, `strava`, `taringa`, `telegram`, `tiki`, `tokopedia`, `treehouse`, `tumblr`, `twitter`, `venmo`, `viber`, `vimeo`, `vivino`, `vkontakte`, `wattpad`, `weibo`, `whatsapp`, `wordpress`, `xing`, `yahoo`, `yandex`, `zalo`, `zoho` nullable, object Result summary object specifying values for `phone` attributes of risk check. \[string\] A list of online services where this phone number has been detected to have accounts or other activity. Possible values: `aboutme`, `adobe`, `adult_sites`, `airbnb`, `altbalaji`, `amazon`, `apple`, `archiveorg`, `atlassian`, `bitmoji`, `bodybuilding`, `booking`, `bukalapak`, `codecademy`, `deliveroo`, `diigo`, `discord`, `disneyplus`, `duolingo`, `ebay`, `envato`, `eventbrite`, `evernote`, `facebook`, `firefox`, `flickr`, `flipkart`, `foursquare`, `freelancer`, `gaana`, `giphy`, `github`, `google`, `gravatar`, `hubspot`, `imgur`, `instagram`, `jdid`, `kakao`, `kommo`, `komoot`, `lastfm`, `lazada`, `line`, `linkedin`, `mailru`, `microsoft`, `myspace`, `netflix`, `nike`, `ok`, `patreon`, `pinterest`, `plurk`, `quora`, `qzone`, `rambler`, `rappi`, `replit`, `samsung`, `seoclerks`, `shopclues`, `skype`, `snapchat`, `snapdeal`, `soundcloud`, `spotify`, `starz`, `strava`, `taringa`, `telegram`, `tiki`, `tokopedia`, `treehouse`, `tumblr`, `twitter`, `venmo`, `viber`, `vimeo`, `vivino`, `vkontakte`, `wattpad`, `weibo`, `whatsapp`, `wordpress`, `xing`, `yahoo`, `yandex`, `zalo`, `zoho` \[object\] Array of result summary objects specifying values for `device` attributes of risk check. nullable, string An enum indicating whether a network proxy is present and if so what type it is. `none_detected` indicates the user is not on a detectable proxy network. `tor` indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). `vpn` indicates the user is on a VPN (Virtual Private Network) `web_proxy` indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. `public_proxy` indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance. Possible values: `none_detected`, `tor`, `vpn`, `web_proxy`, `public_proxy` nullable, integer Count of spam lists the IP address is associated with if known. nullable, string UTC offset of the timezone associated with the IP address. nullable, object Result summary object capturing abuse signals related to `identity abuse`, e.g. stolen and synthetic identity fraud. These attributes are only available for US identities and some signals may not be available depending on what information was collected. nullable, object Field containing the data used in determining the outcome of the synthetic identity risk check. Contains the following fields: `score` - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity. integer A score from 0 to 100 indicating the likelihood that the user is a synthetic identity. nullable, object Field containing the data used in determining the outcome of the stolen identity risk check. Contains the following fields: `score` - A score from 0 to 100 indicating the likelihood that the user is a stolen identity. integer A score from 0 to 100 indicating the likelihood that the user is a stolen identity. \[object\] The attributes related to the facial duplicates captured in risk check. string ID of the associated Identity Verification attempt. integer Similarity score of the match. Ranges from 0 to 100. boolean Whether this match occurred after the session was complete. For example, this would be `true` if a later session ended up matching this one. nullable, integer The trust index score for the `risk_check` step. nullable, object Additional information for the `verify_sms` step. string The outcome status for the associated Identity Verification attempt's `verify_sms` step. This field will always have the same value as `steps.verify_sms`. Possible values: `success`, `failed` \[object\] An array where each entry represents a verification attempt for the `verify_sms` step. Each entry represents one user-submitted phone number. Phone number edits, and in some cases error handling due to edge cases like rate limiting, may generate additional verifications. string The outcome status for the individual SMS verification. Possible values: `pending`, `success`, `failed`, `canceled` integer The attempt field begins with 1 and increments with each subsequent SMS verification. nullable, string A phone number in E.164 format. integer The number of delivery attempts made within the verification to send the SMS code to the user. Each delivery attempt represents the user taking action from the front end UI to request creation and delivery of a new SMS verification code, or to resend an existing SMS verification code. There is a limit of 3 delivery attempts per verification. integer The number of attempts made by the user within the verification to verify the SMS code by entering it into the front end UI. There is a limit of 3 solve attempts per verification. nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string ID of the associated screening. nullable, string ID of the associated Beacon User. nullable, string Unique user identifier, created by calling `/user/create`. Either a `user_id` or the `client_user_id` must be provided. The `user_id` may only be used instead of the `client_user_id` if you were not a pre-existing user of `/user/create` as of December 10, 2025; for more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . If both this field and a `client_user_id` are present in a request, the `user_id` must have been created from the provided `client_user_id`. nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, object Information about a Protect event including Trust Index score and fraud attributes. string The event ID. string The timestamp of the event, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2017-09-14T14:42:19.350Z"` Format: `date-time` nullable, object Represents a calculated Trust Index Score. integer The overall trust index score. string The versioned name of the Trust Index model used for scoring. nullable, object Contains sub-score metadata. nullable, object Represents Trust Index Subscore. integer The subscore score. nullable, object Represents Trust Index Subscore. integer The subscore score. nullable, object Event fraud attributes as an arbitrary set of key-value pairs. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "idv_52xR9LKo77r1Np", "client_user_id": "your-db-id-3b24110", "created_at": "2020-07-24T03:26:02Z", "completed_at": "2020-07-24T03:26:02Z", "previous_attempt_id": "idv_42cF1MNo42r9Xj", "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f", "template": { "id": "idvtmp_4FrXJvfQU3zGUR", "version": 2 }, "user": { "phone_number": "+12345678909", "date_of_birth": "1990-05-29", "ip_address": "192.0.2.42", "email_address": "user@example.com", "name": { "given_name": "Leslie", "family_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "id_number": { "value": "123456789", "type": "us_ssn" } }, "status": "success", "steps": { "accept_tos": "success", "verify_sms": "success", "kyc_check": "success", "documentary_verification": "success", "selfie_check": "success", "watchlist_screening": "success", "risk_check": "success" }, "documentary_verification": { "status": "success", "documents": [ { "status": "success", "attempt": 1, "images": { "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg", "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg", "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg", "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg", "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg" }, "extracted_data": { "id_number": "AB123456", "category": "drivers_license", "expiration_date": "2030-05-29", "issue_date": "2020-05-29", "issuing_country": "US", "issuing_region": "IN", "date_of_birth": "1990-05-29", "address": { "street": "123 Main St. Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "name": { "given_name": "Leslie", "family_name": "Knope" } }, "analysis": { "authenticity": "match", "image_quality": "high", "extracted_data": { "name": "match", "date_of_birth": "match", "expiration_date": "not_expired", "issuing_country": "match" }, "aamva_verification": { "is_verified": true, "id_number": "match", "id_issue_date": "match", "id_expiration_date": "match", "street": "match", "city": "match", "postal_code": "match", "date_of_birth": "match", "gender": "match", "height": "match", "eye_color": "match", "first_name": "match", "middle_name": "match", "last_name": "match" } }, "redacted_at": "2020-07-24T03:26:02Z" } ] }, "selfie_check": { "status": "success", "selfies": [ { "status": "success", "attempt": 1, "capture": { "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg", "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm" }, "analysis": { "document_comparison": "match", "liveness_check": "success" } } ] }, "kyc_check": { "status": "success", "address": { "summary": "match", "po_box": "yes", "type": "residential" }, "name": { "summary": "match" }, "date_of_birth": { "summary": "match" }, "id_number": { "summary": "match" }, "phone_number": { "summary": "match", "area_code": "match" } }, "risk_check": { "status": "success", "behavior": { "user_interactions": "risky", "fraud_ring_detected": "yes", "bot_detected": "yes" }, "email": { "is_deliverable": "yes", "breach_count": 1, "first_breached_at": "1990-05-29", "last_breached_at": "1990-05-29", "domain_registered_at": "1990-05-29", "domain_is_free_provider": "yes", "domain_is_custom": "yes", "domain_is_disposable": "yes", "top_level_domain_is_suspicious": "yes", "linked_services": [ "apple" ] }, "phone": { "linked_services": [ "apple" ] }, "devices": [ { "ip_proxy_type": "none_detected", "ip_spam_list_count": 1, "ip_timezone_offset": "+06:00:00" } ], "identity_abuse_signals": { "synthetic_identity": { "score": 0 }, "stolen_identity": { "score": 0 } }, "facial_duplicates": [ { "id": "idv_52xR9LKo77r1Np", "similarity": 95, "matched_after_completed": true } ], "trust_index_score": 86 }, "verify_sms": { "status": "success", "verifications": [ { "status": "success", "attempt": 1, "phone_number": "+12345678909", "delivery_attempt_count": 1, "solve_attempt_count": 1, "initially_sent_at": "2020-07-24T03:26:02Z", "last_sent_at": "2020-07-24T03:26:02Z", "redacted_at": "2020-07-24T03:26:02Z" } ] }, "watchlist_screening_id": "scr_52xR9LKo77r1Np", "beacon_user_id": "becusr_42cF1MNo42r9Xj", "user_id": "usr_dddAs9ewdcDQQQ", "redacted_at": "2020-07-24T03:26:02Z", "latest_scored_protect_event": { "event_id": "ptevt_7AJYTMFxRUgJ", "timestamp": "2020-07-24T03:26:02Z", "trust_index": { "score": 86, "model": "trust_index.2.0.0", "subscores": { "device_and_connection": { "score": 87 }, "bank_account_insights": { "score": 85 } } }, "fraud_attributes": { "fraud_attributes": { "link_session.linked_bank_accounts.user_pi_matches_owners": true, "link_session.linked_bank_accounts.connected_apps.days_since_first_connection": 582, "session.challenged_with_mfa": false, "user.bank_accounts.num_of_frozen_or_restricted_accounts": 0, "user.linked_bank_accounts.num_family_names": 1, "user.linked_bank_accounts.num_of_connected_banks": 1, "user.link_sessions.days_since_first_link_session": 150, "user.pi.email.history_yrs": 7.03, "user.pi.email.num_social_networks_linked": 12, "user.pi.ssn.user_likely_has_better_ssn": false } } }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /identity\_verification/list  #### List Identity Verifications  Filter and list Identity Verifications created by your account #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string A unique user identifier, created by calling `/user/create`. Either a `user_id` or the `client_user_id` must be provided. The `user_id` may only be used instead of the `client_user_id` if you were not a pre-existing user of `/user/create` as of December 10, 2025; for more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . If both this field and the `client_user_id` are present in the request, the `user_id` must have been created from the provided `client_user_id`. string An identifier that determines which page of results you receive. ```bash curl -X POST https://sandbox.plaid.com/identity_verification/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "template_id": "idvtmp_52xR9LKo77r1Np", "client_user_id": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" }' ``` ```node const request: ListIdentityVerificationRequest = { template_id: 'idvtmp_52xR9LKo77r1Np', client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', }; try { const response = await plaidClient.identityVerificationList(request); } catch (error) { // handle error } ``` ```python request = IdentityVerificationListRequest( template_id='idvtmp_52xR9LKo77r1Np', client_user_id=ClientUserID('user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d') ) response = client.identity_verification_list(request) ``` ```ruby request = Plaid::IdentityVerificationListRequest.new( { template_id: 'idvtmp_52xR9LKo77r1Np', client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' } ) response = client.identity_verification_list(request) ``` ```java IdentityVerificationListRequest request = new IdentityVerificationListRequest() .templateId("idvtmp_52xR9LKo77r1Np") .clientUserId("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"); Response response = client() .identityVerificationList(request) .execute(); ``` ```go request := plaid.NewIdentityVerificationListRequest( "idv_52xR9LKo77r1Np", "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", ) response, _, err := client.PlaidApi. IdentityVerificationList(ctx). IdentityVerificationListRequest(*request). Execute() ``` #### Response fields  \[object\] List of Plaid sessions string ID of the associated Identity Verification attempt. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt. nullable, string A shareable URL that can be sent directly to the user to complete verification object The resource ID and version number of the template configuring the behavior of a given Identity Verification. string ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive. integer Version of the associated Identity Verification template. object The identity data that was either collected from the user or provided via API in order to perform an Identity Verification. nullable, string A valid phone number in E.164 format. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string An IPv4 or IPV6 address. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, object The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. nullable, object Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code nullable, string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. nullable, string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. nullable, string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, object ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be `null`. Otherwise, both fields are guaranteed to be filled. string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` string The status of this Identity Verification attempt. `active` - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed. `success` - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template `failed` - The user failed one or more steps in the session and was told to contact support. `expired` - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future. `canceled` - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed. `pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. Possible values: `active`, `success`, `failed`, `expired`, `canceled`, `pending_review` object Each step will be one of the following values: `active` - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as `active` at any given point. `success` - The Identity Verification attempt has completed this step. `failed` - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session. `waiting_for_prerequisite` - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback. `not_applicable` - This step will not be run for this session. `skipped` - The retry instructions that created this Identity Verification attempt specified that this step should be skipped. `expired` - This step had not yet been completed when the Identity Verification attempt as a whole expired. `canceled` - The Identity Verification attempt was canceled before the user completed this step. `pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. `manually_approved` - The step was manually overridden to pass by a team member in the dashboard. `manually_rejected` - The step was manually overridden to fail by a team member in the dashboard. string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` nullable, object Data, images, analysis, and results from the `documentary_verification` step. This field will be `null` unless `steps.documentary_verification` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `documentary_verification` step. This field will always have the same value as `steps.documentary_verification`. \[object\] An array of documents submitted to the `documentary_verification` step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type. Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within `documents`. If the overall `documentary_verification` is `failed`, the user has exhausted their retry attempts. string An outcome status for this specific document submission. Distinct from the overall `documentary_verification.status` that summarizes the verification outcome from one or more documents. Possible values: `success`, `failed`, `manually_approved` integer The `attempt` field begins with 1 and increments with each subsequent document upload. object URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the `GET` request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires. nullable, string Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document. nullable, string Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected. nullable, string Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document. nullable, string Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected. nullable, string Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo. nullable, object Data extracted from a user-submitted document. nullable, string Alpha-numeric ID number extracted via OCR from the user's document image. string The type of identity document detected in the images provided. Will always be one of the following values: `drivers_license` - A driver's license issued by the associated country, establishing identity without any guarantee as to citizenship, and granting driving privileges `id_card` - A general national identification card, distinct from driver's licenses as it only establishes identity `passport` - A travel passport issued by the associated country for one of its citizens `residence_permit_card` - An identity document issued by the associated country permitting a foreign citizen to _temporarily_ reside there `resident_card` - An identity document issued by the associated country permitting a foreign citizen to _permanently_ reside there `visa` - An identity document issued by the associated country permitting a foreign citizen entry for a short duration and for a specific purpose, typically no longer than 6 months Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say `passport` Possible values: `drivers_license`, `id_card`, `passport`, `residence_permit_card`, `resident_card`, `visa` nullable, string The expiration date of the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string The issue date of the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, object The address extracted from the document. The address must at least contain the following fields to be a valid address: `street`, `city`, `country`. If any are missing or unable to be extracted, the address will be null. `region`, and `postal_code` may be null based on the addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document. string The full street address extracted from the document. string City extracted from the document. nullable, string A subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc. For a full list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they can be inferred from the `country` field. nullable, string The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form. nullable, object The individual's name extracted from the document. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. object High level descriptions of how the associated document was processed. If a document fails verification, the details in the `analysis` object should help clarify why the document was rejected. string High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction. For example, most identity documents have formatting rules like the following: The image of the person's face must have a certain contrast in order to highlight skin tone The subject in the document's image must remove eye glasses and pose in a certain way The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules Security features like watermarks and background patterns must be present So a `match` status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A high level description of the quality of the image the user submitted. For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks. Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality. Possible values: `high`, `medium`, `low` nullable, object Analysis of the data extracted from the submitted document. string A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A description of whether the associated document was expired when the verification was performed. Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be `no_data`. Possible values: `not_expired`, `expired`, `no_data` string A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid. Note: You can configure whether a `no_match` on `issuing_country` fails the `documentary_verification` by editing your Plaid Template. Possible values: `match`, `no_match` nullable, object Analyzed AAMVA data for the associated hit. Note: This field is only available for U.S. driver's licenses issued by participating states. boolean The overall outcome of checking the associated hit against the issuing state database. string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, object Additional information for the `selfie_check` step. This field will be `null` unless `steps.selfie_check` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `selfie_check` step. This field will always have the same value as `steps.selfie_check`. Possible values: `success`, `failed` \[object\] An array of selfies submitted to the `selfie_check` step. Each entry represents one user submission. string An outcome status for this specific selfie. Distinct from the overall `selfie_check.status` that summarizes the verification outcome from one or more selfies. Possible values: `success`, `failed` integer The `attempt` field begins with 1 and increments with each subsequent selfie upload. object The image or video capture of a selfie. Only one of image or video URL will be populated per selfie. nullable, string Temporary URL for downloading an image selfie capture. nullable, string Temporary URL for downloading a video selfie capture. object High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the `analysis` object should help clarify why the selfie was rejected. string Information about the comparison between the selfie and the document (if documentary verification also ran). Possible values: `match`, `no_match`, `no_input` string Assessment of whether the selfie capture is of a real human being, as opposed to a picture of a human on a screen, a picture of a paper cut out, someone wearing a mask, or a deepfake. Possible values: `success`, `failed` nullable, object Additional information for the `kyc_check` (Data Source Verification) step. This field will be `null` unless `steps.kyc_check` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `kyc_check` step. This field will always have the same value as `steps.kyc_check`. object Result summary object specifying how the `address` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string Field describing whether the associated address is a post office box. Will be `yes` when a P.O. box is detected, `no` when Plaid confirmed the address is not a P.O. box, and `no_data` when Plaid was not able to determine if the address is a P.O. box. Possible values: `yes`, `no`, `no_data` string Field describing whether the associated address is being used for commercial or residential purposes. Note: This value will be `no_data` when Plaid does not have sufficient data to determine the address's use. Possible values: `residential`, `commercial`, `no_data` object Result summary object specifying how the `name` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `date_of_birth` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `id_number` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `phone` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` nullable, object Additional information for the `risk_check` step. string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` nullable, object Result summary object specifying values for `behavior` attributes of risk check, when available. string Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session. `genuine` indicates the user has high familiarity with the data they are providing, and that fraud is unlikely. `neutral` indicates some signals are present in between `risky` and `genuine`, but there are not enough clear signals to determine an outcome. `risky` indicates the user has low familiarity with the data they are providing, and that fraud is likely. `no_data` indicates there is not sufficient information to give an accurate signal. Possible values: `genuine`, `neutral`, `risky`, `no_data` string Field describing the outcome of a fraud ring behavior risk check. `yes` indicates that fraud ring activity was detected. `no` indicates that fraud ring activity was not detected. `no_data` indicates there was not enough information available to give an accurate signal. Possible values: `yes`, `no`, `no_data` string Field describing the outcome of a bot detection behavior risk check. `yes` indicates that automated activity was detected. `no` indicates that automated activity was not detected. `no_data` indicates there was not enough information available to give an accurate signal. Possible values: `yes`, `no`, `no_data` nullable, object Result summary object specifying values for `email` attributes of risk check. string SMTP-MX check to confirm the email address exists if known. Possible values: `yes`, `no`, `no_data` nullable, integer Count of all known breaches of this email address if known. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known. Possible values: `yes`, `no`, `no_data` string Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable. Possible values: `yes`, `no`, `no_data` string Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details. Possible values: `yes`, `no`, `no_data` string Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain. Possible values: `yes`, `no`, `no_data` \[string\] A list of online services where this email address has been detected to have accounts or other activity. Possible values: `aboutme`, `adobe`, `adult_sites`, `airbnb`, `altbalaji`, `amazon`, `apple`, `archiveorg`, `atlassian`, `bitmoji`, `bodybuilding`, `booking`, `bukalapak`, `codecademy`, `deliveroo`, `diigo`, `discord`, `disneyplus`, `duolingo`, `ebay`, `envato`, `eventbrite`, `evernote`, `facebook`, `firefox`, `flickr`, `flipkart`, `foursquare`, `freelancer`, `gaana`, `giphy`, `github`, `google`, `gravatar`, `hubspot`, `imgur`, `instagram`, `jdid`, `kakao`, `kommo`, `komoot`, `lastfm`, `lazada`, `line`, `linkedin`, `mailru`, `microsoft`, `myspace`, `netflix`, `nike`, `ok`, `patreon`, `pinterest`, `plurk`, `quora`, `qzone`, `rambler`, `rappi`, `replit`, `samsung`, `seoclerks`, `shopclues`, `skype`, `snapchat`, `snapdeal`, `soundcloud`, `spotify`, `starz`, `strava`, `taringa`, `telegram`, `tiki`, `tokopedia`, `treehouse`, `tumblr`, `twitter`, `venmo`, `viber`, `vimeo`, `vivino`, `vkontakte`, `wattpad`, `weibo`, `whatsapp`, `wordpress`, `xing`, `yahoo`, `yandex`, `zalo`, `zoho` nullable, object Result summary object specifying values for `phone` attributes of risk check. \[string\] A list of online services where this phone number has been detected to have accounts or other activity. Possible values: `aboutme`, `adobe`, `adult_sites`, `airbnb`, `altbalaji`, `amazon`, `apple`, `archiveorg`, `atlassian`, `bitmoji`, `bodybuilding`, `booking`, `bukalapak`, `codecademy`, `deliveroo`, `diigo`, `discord`, `disneyplus`, `duolingo`, `ebay`, `envato`, `eventbrite`, `evernote`, `facebook`, `firefox`, `flickr`, `flipkart`, `foursquare`, `freelancer`, `gaana`, `giphy`, `github`, `google`, `gravatar`, `hubspot`, `imgur`, `instagram`, `jdid`, `kakao`, `kommo`, `komoot`, `lastfm`, `lazada`, `line`, `linkedin`, `mailru`, `microsoft`, `myspace`, `netflix`, `nike`, `ok`, `patreon`, `pinterest`, `plurk`, `quora`, `qzone`, `rambler`, `rappi`, `replit`, `samsung`, `seoclerks`, `shopclues`, `skype`, `snapchat`, `snapdeal`, `soundcloud`, `spotify`, `starz`, `strava`, `taringa`, `telegram`, `tiki`, `tokopedia`, `treehouse`, `tumblr`, `twitter`, `venmo`, `viber`, `vimeo`, `vivino`, `vkontakte`, `wattpad`, `weibo`, `whatsapp`, `wordpress`, `xing`, `yahoo`, `yandex`, `zalo`, `zoho` \[object\] Array of result summary objects specifying values for `device` attributes of risk check. nullable, string An enum indicating whether a network proxy is present and if so what type it is. `none_detected` indicates the user is not on a detectable proxy network. `tor` indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). `vpn` indicates the user is on a VPN (Virtual Private Network) `web_proxy` indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. `public_proxy` indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance. Possible values: `none_detected`, `tor`, `vpn`, `web_proxy`, `public_proxy` nullable, integer Count of spam lists the IP address is associated with if known. nullable, string UTC offset of the timezone associated with the IP address. nullable, object Result summary object capturing abuse signals related to `identity abuse`, e.g. stolen and synthetic identity fraud. These attributes are only available for US identities and some signals may not be available depending on what information was collected. nullable, object Field containing the data used in determining the outcome of the synthetic identity risk check. Contains the following fields: `score` - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity. integer A score from 0 to 100 indicating the likelihood that the user is a synthetic identity. nullable, object Field containing the data used in determining the outcome of the stolen identity risk check. Contains the following fields: `score` - A score from 0 to 100 indicating the likelihood that the user is a stolen identity. integer A score from 0 to 100 indicating the likelihood that the user is a stolen identity. \[object\] The attributes related to the facial duplicates captured in risk check. string ID of the associated Identity Verification attempt. integer Similarity score of the match. Ranges from 0 to 100. boolean Whether this match occurred after the session was complete. For example, this would be `true` if a later session ended up matching this one. nullable, integer The trust index score for the `risk_check` step. nullable, object Additional information for the `verify_sms` step. string The outcome status for the associated Identity Verification attempt's `verify_sms` step. This field will always have the same value as `steps.verify_sms`. Possible values: `success`, `failed` \[object\] An array where each entry represents a verification attempt for the `verify_sms` step. Each entry represents one user-submitted phone number. Phone number edits, and in some cases error handling due to edge cases like rate limiting, may generate additional verifications. string The outcome status for the individual SMS verification. Possible values: `pending`, `success`, `failed`, `canceled` integer The attempt field begins with 1 and increments with each subsequent SMS verification. nullable, string A phone number in E.164 format. integer The number of delivery attempts made within the verification to send the SMS code to the user. Each delivery attempt represents the user taking action from the front end UI to request creation and delivery of a new SMS verification code, or to resend an existing SMS verification code. There is a limit of 3 delivery attempts per verification. integer The number of attempts made by the user within the verification to verify the SMS code by entering it into the front end UI. There is a limit of 3 solve attempts per verification. nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string ID of the associated screening. nullable, string ID of the associated Beacon User. nullable, string Unique user identifier, created by calling `/user/create`. Either a `user_id` or the `client_user_id` must be provided. The `user_id` may only be used instead of the `client_user_id` if you were not a pre-existing user of `/user/create` as of December 10, 2025; for more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . If both this field and a `client_user_id` are present in a request, the `user_id` must have been created from the provided `client_user_id`. nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, object Information about a Protect event including Trust Index score and fraud attributes. string The event ID. string The timestamp of the event, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2017-09-14T14:42:19.350Z"` Format: `date-time` nullable, object Represents a calculated Trust Index Score. integer The overall trust index score. string The versioned name of the Trust Index model used for scoring. nullable, object Contains sub-score metadata. nullable, object Represents Trust Index Subscore. integer The subscore score. nullable, object Represents Trust Index Subscore. integer The subscore score. nullable, object Event fraud attributes as an arbitrary set of key-value pairs. nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "identity_verifications": [ { "id": "idv_52xR9LKo77r1Np", "client_user_id": "your-db-id-3b24110", "created_at": "2020-07-24T03:26:02Z", "completed_at": "2020-07-24T03:26:02Z", "previous_attempt_id": "idv_42cF1MNo42r9Xj", "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f", "template": { "id": "idvtmp_4FrXJvfQU3zGUR", "version": 2 }, "user": { "phone_number": "+12345678909", "date_of_birth": "1990-05-29", "ip_address": "192.0.2.42", "email_address": "user@example.com", "name": { "given_name": "Leslie", "family_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "id_number": { "value": "123456789", "type": "us_ssn" } }, "status": "success", "steps": { "accept_tos": "success", "verify_sms": "success", "kyc_check": "success", "documentary_verification": "success", "selfie_check": "success", "watchlist_screening": "success", "risk_check": "success" }, "documentary_verification": { "status": "success", "documents": [ { "status": "success", "attempt": 1, "images": { "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg", "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg", "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg", "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg", "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg" }, "extracted_data": { "id_number": "AB123456", "category": "drivers_license", "expiration_date": "2030-05-29", "issue_date": "2020-05-29", "issuing_country": "US", "issuing_region": "IN", "date_of_birth": "1990-05-29", "address": { "street": "123 Main St. Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "name": { "given_name": "Leslie", "family_name": "Knope" } }, "analysis": { "authenticity": "match", "image_quality": "high", "extracted_data": { "name": "match", "date_of_birth": "match", "expiration_date": "not_expired", "issuing_country": "match" }, "aamva_verification": { "is_verified": true, "id_number": "match", "id_issue_date": "match", "id_expiration_date": "match", "street": "match", "city": "match", "postal_code": "match", "date_of_birth": "match", "gender": "match", "height": "match", "eye_color": "match", "first_name": "match", "middle_name": "match", "last_name": "match" } }, "redacted_at": "2020-07-24T03:26:02Z" } ] }, "selfie_check": { "status": "success", "selfies": [ { "status": "success", "attempt": 1, "capture": { "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg", "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm" }, "analysis": { "document_comparison": "match", "liveness_check": "success" } } ] }, "kyc_check": { "status": "success", "address": { "summary": "match", "po_box": "yes", "type": "residential" }, "name": { "summary": "match" }, "date_of_birth": { "summary": "match" }, "id_number": { "summary": "match" }, "phone_number": { "summary": "match", "area_code": "match" } }, "risk_check": { "status": "success", "behavior": { "user_interactions": "risky", "fraud_ring_detected": "yes", "bot_detected": "yes" }, "email": { "is_deliverable": "yes", "breach_count": 1, "first_breached_at": "1990-05-29", "last_breached_at": "1990-05-29", "domain_registered_at": "1990-05-29", "domain_is_free_provider": "yes", "domain_is_custom": "yes", "domain_is_disposable": "yes", "top_level_domain_is_suspicious": "yes", "linked_services": [ "apple" ] }, "phone": { "linked_services": [ "apple" ] }, "devices": [ { "ip_proxy_type": "none_detected", "ip_spam_list_count": 1, "ip_timezone_offset": "+06:00:00" } ], "identity_abuse_signals": { "synthetic_identity": { "score": 0 }, "stolen_identity": { "score": 0 } }, "facial_duplicates": [ { "id": "idv_52xR9LKo77r1Np", "similarity": 95, "matched_after_completed": true } ], "trust_index_score": 86 }, "verify_sms": { "status": "success", "verifications": [ { "status": "success", "attempt": 1, "phone_number": "+12345678909", "delivery_attempt_count": 1, "solve_attempt_count": 1, "initially_sent_at": "2020-07-24T03:26:02Z", "last_sent_at": "2020-07-24T03:26:02Z", "redacted_at": "2020-07-24T03:26:02Z" } ] }, "watchlist_screening_id": "scr_52xR9LKo77r1Np", "beacon_user_id": "becusr_42cF1MNo42r9Xj", "user_id": "usr_dddAs9ewdcDQQQ", "redacted_at": "2020-07-24T03:26:02Z", "latest_scored_protect_event": { "event_id": "ptevt_7AJYTMFxRUgJ", "timestamp": "2020-07-24T03:26:02Z", "trust_index": { "score": 86, "model": "trust_index.2.0.0", "subscores": { "device_and_connection": { "score": 87 }, "bank_account_insights": { "score": 85 } } }, "fraud_attributes": { "fraud_attributes": { "link_session.linked_bank_accounts.user_pi_matches_owners": true, "link_session.linked_bank_accounts.connected_apps.days_since_first_connection": 582, "session.challenged_with_mfa": false, "user.bank_accounts.num_of_frozen_or_restricted_accounts": 0, "user.linked_bank_accounts.num_family_names": 1, "user.linked_bank_accounts.num_of_connected_banks": 1, "user.link_sessions.days_since_first_link_session": 150, "user.pi.email.history_yrs": 7.03, "user.pi.email.num_social_networks_linked": 12, "user.pi.ssn.user_likely_has_better_ssn": false } } } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /identity\_verification/retry  #### Retry an Identity Verification  Allow a customer to retry their Identity Verification #### Request fields  required, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. required, string ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive. required, string An instruction specifying what steps the new Identity Verification attempt should require the user to complete: `reset` - Restart the user at the beginning of the session, regardless of whether they successfully completed part of their previous session. `incomplete` - Start the new session at the step that the user failed in the previous session, skipping steps that have already been successfully completed. `infer` - If the most recent Identity Verification attempt associated with the given `client_user_id` has a status of `failed` or `expired`, retry using the `incomplete` strategy. Otherwise, use the `reset` strategy. `custom` - Start the new session with a custom configuration, specified by the value of the `steps` field Note: The `incomplete` strategy cannot be applied if the session's failing step is `screening` or `risk_check`. The `infer` strategy cannot be applied if the session's status is still `active` Possible values: `reset`, `incomplete`, `infer`, `custom` object User information collected outside of Link, most likely via your own onboarding process. Each of the following identity fields are optional: `email_address` `phone_number` `date_of_birth` `name` `address` `id_number` Specifically, these fields are optional in that they can either be fully provided (satisfying every required field in their subschema) or omitted from the request entirely by not providing the key or value. Providing these fields via the API will result in Link skipping the data collection process for the associated user. All verification steps enabled in the associated Identity Verification Template will still be run. Verification steps will either be run immediately, or once the user completes the `accept_tos` step, depending on the value provided to the `gave_consent` field. string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` string A valid phone number in E.164 format. string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` object You can use this field to pre-populate the user's legal name; if it is provided here, they will not be prompted to enter their name in the identity verification attempt. required, string A string with at least one non-whitespace character, with a max length of 100 characters. required, string A string with at least one non-whitespace character, with a max length of 100 characters. object Home address for the user. Supported values are: not provided, address with only country code or full address. For more context on this field, see [Input Validation by Country](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#input-validation-by-country) . string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. required, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. object ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be `null`. Otherwise, both fields are guaranteed to be filled. required, string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . required, string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` object Instructions for the `custom` retry strategy specifying which steps should be required or skipped. Note: This field must be provided when the retry strategy is `custom` and must be omitted otherwise. Custom retries override settings in your Plaid Template. For example, if your Plaid Template has `verify_sms` disabled, a custom retry with `verify_sms` enabled will still require the step. The `selfie_check` step is currently not supported on the sandbox server. Sandbox requests will silently disable the `selfie_check` step when provided. required, boolean A boolean field specifying whether the new session should require or skip the `verify_sms` step. required, boolean A boolean field specifying whether the new session should require or skip the `kyc_check` (Data Source Verification) step. required, boolean A boolean field specifying whether the new session should require or skip the `documentary_verification` step. required, boolean A boolean field specifying whether the new session should require or skip the `selfie_check` step. If a previous session has already passed the `selfie_check` step, the new selfie check will be a Selfie Reauthentication check, in which the selfie is tested for liveness and for consistency with the previous selfie. boolean A flag specifying whether you would like Plaid to expose a shareable URL for the verification being retried. If a value for this flag is not specified, the `is_shareable` setting from the original verification attempt will be used. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```bash curl -X POST https://sandbox.plaid.com/identity_verification/retry \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_user_id": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", "template_id": "idvtmp_52xR9LKo77r1Np", "strategy": "reset", "user": { "email_address": "acharleston@email.com", "phone_number": "+12345678909", "date_of_birth": "1975-01-18", "name": { "given_name": "Anna", "family_name": "Charleston" }, "address": { "street": "100 Market Street", "street2": "Apt 1A", "city": "San Francisco", "region": "CA", "postal_code": "94103", "country": "US" }, "id_number": { "value": "123456789", "type": "us_ssn" } } }' ``` ```node const request: IdentityVerificationRetryRequest = { client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', template_id: 'idvtmp_52xR9LKo77r1Np', strategy: 'reset', user: { email_address: 'acharleston@email.com', phone_number: '+12345678909', date_of_birth: '1975-01-18', name: { given_name: 'Anna', family_name: 'Charleston', }, address: { street: '100 Market Street', street2: 'Apt 1A', city: 'San Francisco', region: 'CA', postal_code: '94103', country: 'US', }, id_number: { value: '123456789', type: 'us_ssn', }, }, }; try { const response = await plaidClient.identityVerificationRetry(request); } catch (error) { // handle error } ``` ```python request = IdentityVerificationRetryRequest( client_user_id=ClientUserID('user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d'), template_id='idvtmp_52xR9LKo77r1Np', strategy=Strategy('RESET'), user=IdentityVerificationRequestUser( email_address='acharleston@email.com', phone_number=IdentityVerificationUserPhoneNumber('+12345678909'), date_of_birth=date(1975, 1, 18), name=IdentityVerificationRequestUserName( given_name='Anna', family_name='Charleston' ), address=UserAddress( street='100 Market Street', street2='Apt 1A', city='San Francisco', region='CA', postal_code='94103', country=GenericCountryCode('US') ), id_number=UserIDNumber( value='123456789', type=IDNumberType('US_SSN') ) ) ) response = client.identity_verification_retry(request) ``` ```ruby request = Plaid::IdentityVerificationRetryRequest.new( { client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', template_id: 'idvtmp_52xR9LKo77r1Np', strategy: Plaid::Strategy::RESET, user: Plaid::IdentityVerificationRequestUser.new( { email_address: 'acharleston@email.com', phone_number: '+12345678909', date_of_birth: Date.new(1975, 1, 18), name: Plaid::IdentityVerificationRequestUserName.new( { given_name: 'Anna', family_name: 'Charleston' } ), address: Plaid::UserAddress.new( { street: '100 Market Street', street2: 'Apt 1A', city: 'San Francisco', region: 'CA', postal_code: '94103', country: 'US' } ), id_number: Plaid::UserIDNumber.new( { value: '123456789', type: Plaid::IDNumberType::US_SSN } ) } ), } ) response = client.identity_verification_retry(request) ``` ```java Strategy strategy = Strategy.RESET; IdentityVerificationRequestUserName name = new IdentityVerificationRequestUserName() .givenName("Anna") .familyName("Charleston"); UserAddress address = new UserAddress() .street("100 Market Street") .street2("Apt 1A") .city("San Francisco") .region("CA") .postalCode("94103") .country("US"); IDNumberType type = IDNumberType.US_SSN; UserIDNumber idNumber = new UserIDNumber() .value("123456789") .type(type); IdentityVerificationRequestUser user = new IdentityVerificationRequestUser() .emailAddress("acharleston@email.com") .phoneNumber("+12345678909") .dateOfBirth(dob) .name(name) .address(address) .idNumber(idNumber); IdentityVerificationRetryRequest request = new IdentityVerificationRetryRequest() .clientUserId("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d") .templateId("idvtmp_52xR9LKo77r1Np") .strategy(strategy) .user(user); Response response = client() .identityVerificationRetry(request) .execute(); ``` ```go user := plaid.NewIdentityVerificationRequestUser() user.SetEmailAddress("acharleston@email.com") user.SetPhoneNumber("+12345678909") user.SetDateOfBirth("1975-01-18") user.SetName( *plaid.NewIdentityVerificationRequestUserName( "Anna", "Charleston", ), ) user.SetAddress( *plaid.NewUserAddress( "100 Market Street", "San Francisco", "CA", "94103", "US", ), ) user.SetIdNumber( *plaid.NewUserIDNumber( "123456789", plaid.IDNUMBERTYPE_US_SSN, ), ) request := plaid.NewIdentityVerificationRetryRequest( "idv_52xR9LKo77r1Np", "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", plaid.STRATEGY_RESET, ) request.SetUser(*user) response, _, err := client.PlaidApi. IdentityVerificationRetry(ctx). IdentityVerificationRetryRequest(*request). Execute() ``` #### Response fields  string ID of the associated Identity Verification attempt. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string The ID for the Identity Verification preceding this session. This field will only be filled if the current Identity Verification is a retry of a previous attempt. nullable, string A shareable URL that can be sent directly to the user to complete verification object The resource ID and version number of the template configuring the behavior of a given Identity Verification. string ID of the associated Identity Verification template. Like all Plaid identifiers, this is case-sensitive. integer Version of the associated Identity Verification template. object The identity data that was either collected from the user or provided via API in order to perform an Identity Verification. nullable, string A valid phone number in E.164 format. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string An IPv4 or IPV6 address. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, object The full name provided by the user. If the user has not submitted their name, this field will be null. Otherwise, both fields are guaranteed to be filled. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. nullable, object Even if an address has been collected, some fields may be null depending on the region's addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code nullable, string The primary street portion of an address. If an address is provided, this field will always be filled. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. nullable, string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. nullable, string City from the address. A string with at least one non-whitespace alphabetical character, with a max length of 100 characters. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string The postal code for the associated address. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, object ID number submitted by the user, currently used only for the Identity Verification product. If the user has not submitted this data yet, this field will be `null`. Otherwise, both fields are guaranteed to be filled. string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` string The status of this Identity Verification attempt. `active` - The Identity Verification attempt is incomplete. The user may have completed part of the session, but has neither failed or passed. `success` - The Identity Verification attempt has completed, passing all steps defined to the associated Identity Verification template `failed` - The user failed one or more steps in the session and was told to contact support. `expired` - The Identity Verification attempt was active for a long period of time without being completed and was automatically marked as expired. Note that sessions currently do not expire. Automatic expiration is expected to be enabled in the future. `canceled` - The Identity Verification attempt was canceled, either via the dashboard by a user, or via API. The user may have completed part of the session, but has neither failed or passed. `pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. Possible values: `active`, `success`, `failed`, `expired`, `canceled`, `pending_review` object Each step will be one of the following values: `active` - This step is the user's current step. They are either in the process of completing this step, or they recently closed their Identity Verification attempt while in the middle of this step. Only one step will be marked as `active` at any given point. `success` - The Identity Verification attempt has completed this step. `failed` - The user failed this step. This can either call the user to fail the session as a whole, or cause them to fallback to another step depending on how the Identity Verification template is configured. A failed step does not imply a failed session. `waiting_for_prerequisite` - The user needs to complete another step first, before they progress to this step. This step may never run, depending on if the user fails an earlier step or if the step is only run as a fallback. `not_applicable` - This step will not be run for this session. `skipped` - The retry instructions that created this Identity Verification attempt specified that this step should be skipped. `expired` - This step had not yet been completed when the Identity Verification attempt as a whole expired. `canceled` - The Identity Verification attempt was canceled before the user completed this step. `pending_review` - The Identity Verification attempt template was configured to perform a screening that had one or more hits needing review. `manually_approved` - The step was manually overridden to pass by a team member in the dashboard. `manually_rejected` - The step was manually overridden to fail by a team member in the dashboard. string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` nullable, object Data, images, analysis, and results from the `documentary_verification` step. This field will be `null` unless `steps.documentary_verification` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `documentary_verification` step. This field will always have the same value as `steps.documentary_verification`. \[object\] An array of documents submitted to the `documentary_verification` step. Each entry represents one user submission, where each submission will contain both a front and back image, or just a front image, depending on the document type. Note: Plaid will automatically let a user submit a new set of document images up to three times if we detect that a previous attempt might have failed due to user error. For example, if the first set of document images are blurry or obscured by glare, the user will be asked to capture their documents again, resulting in at least two separate entries within `documents`. If the overall `documentary_verification` is `failed`, the user has exhausted their retry attempts. string An outcome status for this specific document submission. Distinct from the overall `documentary_verification.status` that summarizes the verification outcome from one or more documents. Possible values: `success`, `failed`, `manually_approved` integer The `attempt` field begins with 1 and increments with each subsequent document upload. object URLs for downloading original and cropped images for this document submission. The URLs are designed to only allow downloading, not hot linking, so the URL will only serve the document image for 60 seconds before expiring. The expiration time is 60 seconds after the `GET` request for the associated Identity Verification attempt. A new expiring URL is generated with each request, so you can always rerequest the Identity Verification attempt if one of your URLs expires. nullable, string Temporary URL that expires after 60 seconds for downloading the uncropped original image of the front of the document. nullable, string Temporary URL that expires after 60 seconds for downloading the original image of the back of the document. Might be null if the back of the document was not collected. nullable, string Temporary URL that expires after 60 seconds for downloading a cropped image containing just the front of the document. nullable, string Temporary URL that expires after 60 seconds for downloading a cropped image containing just the back of the document. Might be null if the back of the document was not collected. nullable, string Temporary URL that expires after 60 seconds for downloading a crop of just the user's face from the document image. Might be null if the document does not contain a face photo. nullable, object Data extracted from a user-submitted document. nullable, string Alpha-numeric ID number extracted via OCR from the user's document image. string The type of identity document detected in the images provided. Will always be one of the following values: `drivers_license` - A driver's license issued by the associated country, establishing identity without any guarantee as to citizenship, and granting driving privileges `id_card` - A general national identification card, distinct from driver's licenses as it only establishes identity `passport` - A travel passport issued by the associated country for one of its citizens `residence_permit_card` - An identity document issued by the associated country permitting a foreign citizen to _temporarily_ reside there `resident_card` - An identity document issued by the associated country permitting a foreign citizen to _permanently_ reside there `visa` - An identity document issued by the associated country permitting a foreign citizen entry for a short duration and for a specific purpose, typically no longer than 6 months Note: This value may be different from the ID type that the user selects within Link. For example, if they select "Driver's License" but then submit a picture of a passport, this field will say `passport` Possible values: `drivers_license`, `id_card`, `passport`, `residence_permit_card`, `resident_card`, `visa` nullable, string The expiration date of the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string The issue date of the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A subdivision code. "Subdivision" is a generic term for "state", "province", "prefecture", "zone", etc. For the list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they are inferred from the `country` field. nullable, string A date extracted from the document in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, object The address extracted from the document. The address must at least contain the following fields to be a valid address: `street`, `city`, `country`. If any are missing or unable to be extracted, the address will be null. `region`, and `postal_code` may be null based on the addressing system. For example: Addresses from the United Kingdom will not include a region Addresses from Hong Kong will not include postal code Note: Optical Character Recognition (OCR) technology may sometimes extract incorrect data from a document. string The full street address extracted from the document. string City extracted from the document. nullable, string A subdivision code extracted from the document. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc. For a full list of valid codes, see [country subdivision codes](https://plaid.com/documents/country_subdivision_codes.json) . Country prefixes are omitted, since they can be inferred from the `country` field. nullable, string The postal code extracted from the document. Between 2 and 10 alphanumeric characters. For US-based addresses this must be 5 numeric digits. string Valid, capitalized, two-letter ISO code representing the country extracted from the document. Must be in ISO 3166-1 alpha-2 form. nullable, object The individual's name extracted from the document. string A string with at least one non-whitespace character, with a max length of 100 characters. string A string with at least one non-whitespace character, with a max length of 100 characters. object High level descriptions of how the associated document was processed. If a document fails verification, the details in the `analysis` object should help clarify why the document was rejected. string High level summary of whether the document in the provided image matches the formatting rules and security checks for the associated jurisdiction. For example, most identity documents have formatting rules like the following: The image of the person's face must have a certain contrast in order to highlight skin tone The subject in the document's image must remove eye glasses and pose in a certain way The informational fields (name, date of birth, ID number, etc.) must be colored and aligned according to specific rules Security features like watermarks and background patterns must be present So a `match` status for this field indicates that the document in the provided image seems to conform to the various formatting and security rules associated with the detected document. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A high level description of the quality of the image the user submitted. For example, an image that is blurry, distorted by glare from a nearby light source, or improperly framed might be marked as low or medium quality. Poor quality images are more likely to fail OCR and/or template conformity checks. Note: By default, Plaid will let a user recapture document images twice before failing the entire session if we attribute the failure to low image quality. Possible values: `high`, `medium`, `low` nullable, object Analysis of the data extracted from the submitted document. string A match summary describing the cross comparison between the subject's name, extracted from the document image, and the name they separately provided to identity verification attempt. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A match summary describing the cross comparison between the subject's date of birth, extracted from the document image, and the date of birth they separately provided to the identity verification attempt. Possible values: `match`, `partial_match`, `no_match`, `no_data` string A description of whether the associated document was expired when the verification was performed. Note: In the case where an expiration date is not present on the document or failed to be extracted, this value will be `no_data`. Possible values: `not_expired`, `expired`, `no_data` string A binary match indicator specifying whether the country that issued the provided document matches the country that the user separately provided to Plaid. Note: You can configure whether a `no_match` on `issuing_country` fails the `documentary_verification` by editing your Plaid Template. Possible values: `match`, `no_match` nullable, object Analyzed AAMVA data for the associated hit. Note: This field is only available for U.S. driver's licenses issued by participating states. boolean The overall outcome of checking the associated hit against the issuing state database. string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the particular field against state databases. `match` - The field is an exact match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` string The outcome of checking the associated hit against state databases. `match` - The field is an exact match with the state database. `partial_match` - The field is a partial match with the state database. `no_match` - The field is not an exact match with the state database. `no_data` - The field was unable to be checked against state databases. Possible values: `match`, `partial_match`, `no_match`, `no_data` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, object Additional information for the `selfie_check` step. This field will be `null` unless `steps.selfie_check` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `selfie_check` step. This field will always have the same value as `steps.selfie_check`. Possible values: `success`, `failed` \[object\] An array of selfies submitted to the `selfie_check` step. Each entry represents one user submission. string An outcome status for this specific selfie. Distinct from the overall `selfie_check.status` that summarizes the verification outcome from one or more selfies. Possible values: `success`, `failed` integer The `attempt` field begins with 1 and increments with each subsequent selfie upload. object The image or video capture of a selfie. Only one of image or video URL will be populated per selfie. nullable, string Temporary URL for downloading an image selfie capture. nullable, string Temporary URL for downloading a video selfie capture. object High level descriptions of how the associated selfie was processed. If a selfie fails verification, the details in the `analysis` object should help clarify why the selfie was rejected. string Information about the comparison between the selfie and the document (if documentary verification also ran). Possible values: `match`, `no_match`, `no_input` string Assessment of whether the selfie capture is of a real human being, as opposed to a picture of a human on a screen, a picture of a paper cut out, someone wearing a mask, or a deepfake. Possible values: `success`, `failed` nullable, object Additional information for the `kyc_check` (Data Source Verification) step. This field will be `null` unless `steps.kyc_check` has reached a terminal state of either `success` or `failed`. string The outcome status for the associated Identity Verification attempt's `kyc_check` step. This field will always have the same value as `steps.kyc_check`. object Result summary object specifying how the `address` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string Field describing whether the associated address is a post office box. Will be `yes` when a P.O. box is detected, `no` when Plaid confirmed the address is not a P.O. box, and `no_data` when Plaid was not able to determine if the address is a P.O. box. Possible values: `yes`, `no`, `no_data` string Field describing whether the associated address is being used for commercial or residential purposes. Note: This value will be `no_data` when Plaid does not have sufficient data to determine the address's use. Possible values: `residential`, `commercial`, `no_data` object Result summary object specifying how the `name` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `date_of_birth` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `id_number` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Result summary object specifying how the `phone` field matched. string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` nullable, object Additional information for the `risk_check` step. string The status of a step in the Identity Verification process. Possible values: `success`, `active`, `failed`, `waiting_for_prerequisite`, `not_applicable`, `skipped`, `expired`, `canceled`, `pending_review`, `manually_approved`, `manually_rejected` nullable, object Result summary object specifying values for `behavior` attributes of risk check, when available. string Field describing the overall user interaction signals of a behavior risk check. This value represents how familiar the user is with the personal data they provide, based on a number of signals that are collected during their session. `genuine` indicates the user has high familiarity with the data they are providing, and that fraud is unlikely. `neutral` indicates some signals are present in between `risky` and `genuine`, but there are not enough clear signals to determine an outcome. `risky` indicates the user has low familiarity with the data they are providing, and that fraud is likely. `no_data` indicates there is not sufficient information to give an accurate signal. Possible values: `genuine`, `neutral`, `risky`, `no_data` string Field describing the outcome of a fraud ring behavior risk check. `yes` indicates that fraud ring activity was detected. `no` indicates that fraud ring activity was not detected. `no_data` indicates there was not enough information available to give an accurate signal. Possible values: `yes`, `no`, `no_data` string Field describing the outcome of a bot detection behavior risk check. `yes` indicates that automated activity was detected. `no` indicates that automated activity was not detected. `no_data` indicates there was not enough information available to give an accurate signal. Possible values: `yes`, `no`, `no_data` nullable, object Result summary object specifying values for `email` attributes of risk check. string SMTP-MX check to confirm the email address exists if known. Possible values: `yes`, `no`, `no_data` nullable, integer Count of all known breaches of this email address if known. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string Indicates whether the email address domain is a free provider such as Gmail or Hotmail if known. Possible values: `yes`, `no`, `no_data` string Indicates whether the email address domain is custom if known, i.e. a company domain and not free or disposable. Possible values: `yes`, `no`, `no_data` string Indicates whether the email domain is listed as disposable if known. Disposable domains are often used to create email addresses that are part of a fake set of user details. Possible values: `yes`, `no`, `no_data` string Indicates whether the email address top level domain, which is the last part of the domain, is fraudulent or risky if known. In most cases, a suspicious top level domain is also associated with a disposable or high-risk domain. Possible values: `yes`, `no`, `no_data` \[string\] A list of online services where this email address has been detected to have accounts or other activity. Possible values: `aboutme`, `adobe`, `adult_sites`, `airbnb`, `altbalaji`, `amazon`, `apple`, `archiveorg`, `atlassian`, `bitmoji`, `bodybuilding`, `booking`, `bukalapak`, `codecademy`, `deliveroo`, `diigo`, `discord`, `disneyplus`, `duolingo`, `ebay`, `envato`, `eventbrite`, `evernote`, `facebook`, `firefox`, `flickr`, `flipkart`, `foursquare`, `freelancer`, `gaana`, `giphy`, `github`, `google`, `gravatar`, `hubspot`, `imgur`, `instagram`, `jdid`, `kakao`, `kommo`, `komoot`, `lastfm`, `lazada`, `line`, `linkedin`, `mailru`, `microsoft`, `myspace`, `netflix`, `nike`, `ok`, `patreon`, `pinterest`, `plurk`, `quora`, `qzone`, `rambler`, `rappi`, `replit`, `samsung`, `seoclerks`, `shopclues`, `skype`, `snapchat`, `snapdeal`, `soundcloud`, `spotify`, `starz`, `strava`, `taringa`, `telegram`, `tiki`, `tokopedia`, `treehouse`, `tumblr`, `twitter`, `venmo`, `viber`, `vimeo`, `vivino`, `vkontakte`, `wattpad`, `weibo`, `whatsapp`, `wordpress`, `xing`, `yahoo`, `yandex`, `zalo`, `zoho` nullable, object Result summary object specifying values for `phone` attributes of risk check. \[string\] A list of online services where this phone number has been detected to have accounts or other activity. Possible values: `aboutme`, `adobe`, `adult_sites`, `airbnb`, `altbalaji`, `amazon`, `apple`, `archiveorg`, `atlassian`, `bitmoji`, `bodybuilding`, `booking`, `bukalapak`, `codecademy`, `deliveroo`, `diigo`, `discord`, `disneyplus`, `duolingo`, `ebay`, `envato`, `eventbrite`, `evernote`, `facebook`, `firefox`, `flickr`, `flipkart`, `foursquare`, `freelancer`, `gaana`, `giphy`, `github`, `google`, `gravatar`, `hubspot`, `imgur`, `instagram`, `jdid`, `kakao`, `kommo`, `komoot`, `lastfm`, `lazada`, `line`, `linkedin`, `mailru`, `microsoft`, `myspace`, `netflix`, `nike`, `ok`, `patreon`, `pinterest`, `plurk`, `quora`, `qzone`, `rambler`, `rappi`, `replit`, `samsung`, `seoclerks`, `shopclues`, `skype`, `snapchat`, `snapdeal`, `soundcloud`, `spotify`, `starz`, `strava`, `taringa`, `telegram`, `tiki`, `tokopedia`, `treehouse`, `tumblr`, `twitter`, `venmo`, `viber`, `vimeo`, `vivino`, `vkontakte`, `wattpad`, `weibo`, `whatsapp`, `wordpress`, `xing`, `yahoo`, `yandex`, `zalo`, `zoho` \[object\] Array of result summary objects specifying values for `device` attributes of risk check. nullable, string An enum indicating whether a network proxy is present and if so what type it is. `none_detected` indicates the user is not on a detectable proxy network. `tor` indicates the user was using a Tor browser, which sends encrypted traffic on a decentralized network and is somewhat similar to a VPN (Virtual Private Network). `vpn` indicates the user is on a VPN (Virtual Private Network) `web_proxy` indicates the user is on a web proxy server, which may allow them to conceal information such as their IP address or other identifying information. `public_proxy` indicates the user is on a public web proxy server, which is similar to a web proxy but can be shared by multiple users. This may allow multiple users to appear as if they have the same IP address for instance. Possible values: `none_detected`, `tor`, `vpn`, `web_proxy`, `public_proxy` nullable, integer Count of spam lists the IP address is associated with if known. nullable, string UTC offset of the timezone associated with the IP address. nullable, object Result summary object capturing abuse signals related to `identity abuse`, e.g. stolen and synthetic identity fraud. These attributes are only available for US identities and some signals may not be available depending on what information was collected. nullable, object Field containing the data used in determining the outcome of the synthetic identity risk check. Contains the following fields: `score` - A score from 0 to 100 indicating the likelihood that the user is a synthetic identity. integer A score from 0 to 100 indicating the likelihood that the user is a synthetic identity. nullable, object Field containing the data used in determining the outcome of the stolen identity risk check. Contains the following fields: `score` - A score from 0 to 100 indicating the likelihood that the user is a stolen identity. integer A score from 0 to 100 indicating the likelihood that the user is a stolen identity. \[object\] The attributes related to the facial duplicates captured in risk check. string ID of the associated Identity Verification attempt. integer Similarity score of the match. Ranges from 0 to 100. boolean Whether this match occurred after the session was complete. For example, this would be `true` if a later session ended up matching this one. nullable, integer The trust index score for the `risk_check` step. nullable, object Additional information for the `verify_sms` step. string The outcome status for the associated Identity Verification attempt's `verify_sms` step. This field will always have the same value as `steps.verify_sms`. Possible values: `success`, `failed` \[object\] An array where each entry represents a verification attempt for the `verify_sms` step. Each entry represents one user-submitted phone number. Phone number edits, and in some cases error handling due to edge cases like rate limiting, may generate additional verifications. string The outcome status for the individual SMS verification. Possible values: `pending`, `success`, `failed`, `canceled` integer The attempt field begins with 1 and increments with each subsequent SMS verification. nullable, string A phone number in E.164 format. integer The number of delivery attempts made within the verification to send the SMS code to the user. Each delivery attempt represents the user taking action from the front end UI to request creation and delivery of a new SMS verification code, or to resend an existing SMS verification code. There is a limit of 3 delivery attempts per verification. integer The number of attempts made by the user within the verification to verify the SMS code by entering it into the front end UI. There is a limit of 3 solve attempts per verification. nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string ID of the associated screening. nullable, string ID of the associated Beacon User. nullable, string Unique user identifier, created by calling `/user/create`. Either a `user_id` or the `client_user_id` must be provided. The `user_id` may only be used instead of the `client_user_id` if you were not a pre-existing user of `/user/create` as of December 10, 2025; for more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . If both this field and a `client_user_id` are present in a request, the `user_id` must have been created from the provided `client_user_id`. nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, object Information about a Protect event including Trust Index score and fraud attributes. string The event ID. string The timestamp of the event, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2017-09-14T14:42:19.350Z"` Format: `date-time` nullable, object Represents a calculated Trust Index Score. integer The overall trust index score. string The versioned name of the Trust Index model used for scoring. nullable, object Contains sub-score metadata. nullable, object Represents Trust Index Subscore. integer The subscore score. nullable, object Represents Trust Index Subscore. integer The subscore score. nullable, object Event fraud attributes as an arbitrary set of key-value pairs. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "idv_52xR9LKo77r1Np", "client_user_id": "your-db-id-3b24110", "created_at": "2020-07-24T03:26:02Z", "completed_at": "2020-07-24T03:26:02Z", "previous_attempt_id": "idv_42cF1MNo42r9Xj", "shareable_url": "https://flow.plaid.com/verify/idv_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f", "template": { "id": "idvtmp_4FrXJvfQU3zGUR", "version": 2 }, "user": { "phone_number": "+12345678909", "date_of_birth": "1990-05-29", "ip_address": "192.0.2.42", "email_address": "user@example.com", "name": { "given_name": "Leslie", "family_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "id_number": { "value": "123456789", "type": "us_ssn" } }, "status": "success", "steps": { "accept_tos": "success", "verify_sms": "success", "kyc_check": "success", "documentary_verification": "success", "selfie_check": "success", "watchlist_screening": "success", "risk_check": "success" }, "documentary_verification": { "status": "success", "documents": [ { "status": "success", "attempt": 1, "images": { "original_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_front.jpeg", "original_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/original_back.jpeg", "cropped_front": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_front.jpeg", "cropped_back": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/cropped_back.jpeg", "face": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/documents/1/face.jpeg" }, "extracted_data": { "id_number": "AB123456", "category": "drivers_license", "expiration_date": "2030-05-29", "issue_date": "2020-05-29", "issuing_country": "US", "issuing_region": "IN", "date_of_birth": "1990-05-29", "address": { "street": "123 Main St. Unit 42", "city": "Pawnee", "region": "IN", "postal_code": "46001", "country": "US" }, "name": { "given_name": "Leslie", "family_name": "Knope" } }, "analysis": { "authenticity": "match", "image_quality": "high", "extracted_data": { "name": "match", "date_of_birth": "match", "expiration_date": "not_expired", "issuing_country": "match" }, "aamva_verification": { "is_verified": true, "id_number": "match", "id_issue_date": "match", "id_expiration_date": "match", "street": "match", "city": "match", "postal_code": "match", "date_of_birth": "match", "gender": "match", "height": "match", "eye_color": "match", "first_name": "match", "middle_name": "match", "last_name": "match" } }, "redacted_at": "2020-07-24T03:26:02Z" } ] }, "selfie_check": { "status": "success", "selfies": [ { "status": "success", "attempt": 1, "capture": { "image_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.jpeg", "video_url": "https://example.plaid.com/verifications/idv_52xR9LKo77r1Np/selfie/liveness.webm" }, "analysis": { "document_comparison": "match", "liveness_check": "success" } } ] }, "kyc_check": { "status": "success", "address": { "summary": "match", "po_box": "yes", "type": "residential" }, "name": { "summary": "match" }, "date_of_birth": { "summary": "match" }, "id_number": { "summary": "match" }, "phone_number": { "summary": "match", "area_code": "match" } }, "risk_check": { "status": "success", "behavior": { "user_interactions": "risky", "fraud_ring_detected": "yes", "bot_detected": "yes" }, "email": { "is_deliverable": "yes", "breach_count": 1, "first_breached_at": "1990-05-29", "last_breached_at": "1990-05-29", "domain_registered_at": "1990-05-29", "domain_is_free_provider": "yes", "domain_is_custom": "yes", "domain_is_disposable": "yes", "top_level_domain_is_suspicious": "yes", "linked_services": [ "apple" ] }, "phone": { "linked_services": [ "apple" ] }, "devices": [ { "ip_proxy_type": "none_detected", "ip_spam_list_count": 1, "ip_timezone_offset": "+06:00:00" } ], "identity_abuse_signals": { "synthetic_identity": { "score": 0 }, "stolen_identity": { "score": 0 } }, "facial_duplicates": [ { "id": "idv_52xR9LKo77r1Np", "similarity": 95, "matched_after_completed": true } ], "trust_index_score": 86 }, "verify_sms": { "status": "success", "verifications": [ { "status": "success", "attempt": 1, "phone_number": "+12345678909", "delivery_attempt_count": 1, "solve_attempt_count": 1, "initially_sent_at": "2020-07-24T03:26:02Z", "last_sent_at": "2020-07-24T03:26:02Z", "redacted_at": "2020-07-24T03:26:02Z" } ] }, "watchlist_screening_id": "scr_52xR9LKo77r1Np", "beacon_user_id": "becusr_42cF1MNo42r9Xj", "user_id": "usr_dddAs9ewdcDQQQ", "redacted_at": "2020-07-24T03:26:02Z", "latest_scored_protect_event": { "event_id": "ptevt_7AJYTMFxRUgJ", "timestamp": "2020-07-24T03:26:02Z", "trust_index": { "score": 86, "model": "trust_index.2.0.0", "subscores": { "device_and_connection": { "score": 87 }, "bank_account_insights": { "score": 85 } } }, "fraud_attributes": { "fraud_attributes": { "link_session.linked_bank_accounts.user_pi_matches_owners": true, "link_session.linked_bank_accounts.connected_apps.days_since_first_connection": 582, "session.challenged_with_mfa": false, "user.bank_accounts.num_of_frozen_or_restricted_accounts": 0, "user.linked_bank_accounts.num_family_names": 1, "user.linked_bank_accounts.num_of_connected_banks": 1, "user.link_sessions.days_since_first_link_session": 150, "user.pi.email.history_yrs": 7.03, "user.pi.email.num_social_networks_linked": 12, "user.pi.ssn.user_likely_has_better_ssn": false } } }, "request_id": "saKrIBuEB9qJZng" } ``` ### Webhooks  \=\*=\*=\*= #### STATUS\_UPDATED  Fired when the status of an identity verification has been updated, which can be triggered via the dashboard or the API. #### Properties  string `IDENTITY_VERIFICATION` string `STATUS_UPDATED` string The ID of the associated Identity Verification attempt. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "IDENTITY_VERIFICATION", "webhook_code": "STATUS_UPDATED", "identity_verification_id": "idv_52xR9LKo77r1Np", "environment": "production" } ``` \=\*=\*=\*= #### STEP\_UPDATED  Fired when an end user has completed a step of the Identity Verification process. #### Properties  string `IDENTITY_VERIFICATION` string `STEP_UPDATED` string The ID of the associated Identity Verification attempt. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "IDENTITY_VERIFICATION", "webhook_code": "STEP_UPDATED", "identity_verification_id": "idv_52xR9LKo77r1Np", "environment": "production" } ``` \=\*=\*=\*= #### RETRIED  Fired when identity verification has been retried, which can be triggered via the dashboard or the API. #### Properties  string `IDENTITY_VERIFICATION` string `RETRIED` string The ID of the associated Identity Verification attempt. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "IDENTITY_VERIFICATION", "webhook_code": "RETRIED", "identity_verification_id": "idv_52xR9LKo77r1Np", "environment": "production" } ``` --- # API - Identity | Plaid Docs Identity  ========= #### API reference for Identity endpoints and webhooks  Verify the name, address, phone number, and email address of a user against bank account information on file. For how-to guidance, see the [Identity documentation](https://plaid.com/docs/identity/index.html.md) . | Endpoints | | | --- | --- | | [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) | Fetch identity data | | [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) | Match client identity with bank identity | | [/identity/documents/uploads/get](https://plaid.com/docs/api/products/identity/index.html.md#identitydocumentsuploadsget) | Get Identity data parsed from an uploaded bank statement | ### Endpoints  \=\*=\*=\*= #### /identity/get  #### Retrieve identity data  The [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) endpoint allows you to retrieve various account holder information on file with the financial institution, including names, emails, phone numbers, and addresses. Only name data is guaranteed to be returned; other fields will be empty arrays if not provided by the institution. Note: In API versions 2018-05-22 and earlier, the `owners` object is not returned, and instead identity information is returned in the top level `identity` object. For more details, see [Plaid API versioning](https://plaid.com/docs/api/versioning/index.html.md#version-2019-05-29) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. object An optional object to filter `/identity/get` results. \[string\] A list of `account_ids` to retrieve for the Item. Note: An error will be returned if a provided `account_id` is not associated with the Item. ```ruby # pull identity data for an item request = Plaid::IdentityGetRequest.new({ access_token: access_token }) response = client.identity_get(request) accounts = response.accounts identities = accounts.map { |account| account.owners }.flatten ``` ```bash curl -X POST https://sandbox.plaid.com/identity/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node // Pull Identity data for an Item const request: IdentityGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.identityGet(request); const identities = response.data.accounts.flatMap( (account) => account.owners, ); } catch (error) { // handle error } ``` ```java // Pull Identity data for an Item IdentityGetRequest request = new IdentityGetRequest() .accessToken(accessToken); Response response = client().identityGet(request).execute(); // Java 7 List accounts = response.body().getAccounts(); List identities = new ArrayList<>(); for (IdentityGetResponse.AccountWithOwners account : accounts) { identities.addAll(account.getOwners()); } // Java 8 and above List accounts = response.body().getAccounts(); List identities = accounts.stream() .flatMap(account -> account.getOwners().stream()) .collect(Collectors.toList()); ``` ```python # pull identity data for an item request = IdentityGetRequest(access_token=access_token) response = client.identity_get(request) accounts = response['accounts'] identities = [] for account in accounts: identities.extend(account['owners']) ``` ```go request := plaid.NewIdentityGetRequest(accessToken) response, _, err := client.PlaidApi.IdentityGet(ctx).IdentityGetRequest( *request, ).Execute() accounts := response.GetAccounts() ``` #### Response fields  \[object\] The accounts for which Identity data has been requested string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution; detecting whether the linked account is a business account is not currently supported. Multiple owners on a single account will be represented in the same `owner` object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the `owners` object is not returned, and instead identity information is returned in the top level `identity` object. For more details, see [Plaid API versioning](https://plaid.com/docs/api/versioning/index.html.md#version-2019-05-29) \[string\] A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's `names` array. \[object\] A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The phone number. boolean When `true`, identifies the phone number as the primary number on an account. string The type of phone number. Possible values: `home`, `work`, `office`, `mobile`, `mobile1`, `other` \[object\] A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The email address. boolean When `true`, identifies the email address as the primary email on an account. string The type of email account as described by the financial institution. Possible values: `primary`, `secondary`, `other` \[object\] Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. object Data about the components comprising an address. nullable, string The full city name nullable, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code boolean When `true`, identifies the address as the primary address on an account. object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "accounts": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "postal_code": "93405-2255", "region": "CA", "street": "2493 Leisure Lane" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholder1@example.com", "primary": false, "type": "secondary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "2025550123", "primary": false, "type": "home" }, { "data": "1112224444", "primary": false, "type": "work" }, { "data": "1112225555", "primary": false, "type": "mobile" } ] } ], "subtype": "checking", "type": "depository" }, { "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "balances": { "available": 200, "current": 210, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "1111", "name": "Plaid Saving", "official_name": "Plaid Silver Standard 0.1% Interest Saving", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "postal_code": "93405-2255", "region": "CA", "street": "2493 Leisure Lane" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholder1@example.com", "primary": false, "type": "secondary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "2025550123", "primary": false, "type": "home" }, { "data": "1112224444", "primary": false, "type": "work" }, { "data": "1112225555", "primary": false, "type": "mobile" } ] } ], "subtype": "savings", "type": "depository" } ], "item": { "available_products": [ "balance", "investments" ], "billed_products": [ "assets", "auth", "identity", "liabilities", "transactions" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_3", "institution_name": "Chase", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook", "auth_method": "INSTANT_AUTH" }, "request_id": "3nARps6TOYtbACO" } ``` \=\*=\*=\*= #### /identity/match  #### Retrieve identity match score  The [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) endpoint generates a match score, which indicates how well the provided identity data matches the identity information on file with the account holder's financial institution. Fields within the `balances` object will always be null when retrieved by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) . Instead, use the free [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint to request balance cached data, or [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) or [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) for real-time data. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. object The user's legal name, phone number, email address and address used to perform fuzzy match. If Financial Account Matching is enabled in the Identity Verification product, leave this field empty to automatically match against PII collected from the Identity Verification checks. string The user's full legal name. string The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. string The user's email address. object Data about the components comprising an address. string The full city name string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. string The ISO 3166-1 alpha-2 country code object An optional object to filter /identity/match results \[string\] An array of `account_ids` to perform fuzzy match ```ruby # Omit user object if using identity verification / financial account matching user = Plaid::IdentityMatchUser.new( legal_name: 'Jane Smith', phone_number: '+14155552671', email_address: 'jane.smith@example.com', address: Plaid::AddressDataNullableNoRequiredFields.new( street: '500 Market St', city: 'San Francisco', region: 'CA', postal_code: '94105', country: 'US' ) ) request = Plaid::IdentityMatchRequest.new( access_token: access_token, user: user ) response = client.identity_match(request) accounts = response.accounts accounts.map do |account| name_score = account.legal_name&.score phone_score = account.phone_number&.score email_score = account.email_address&.score address_score = account.address&.score end ``` ```bash # Omit user object if using Identity Verification / Financial Account Matching curl -X POST https://sandbox.plaid.com/identity/match \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "user": { "phone_number": String, "legal_name": String, "email_address": String, "address": { "street": String, "region": String, "country": String, "city": String, "postal_code": String } } }' ``` ```node const request = { access_token: accessToken, // Omit user object if using Identity Verification Financial Account Matching user: { legal_name: 'Jane Smith', phone_number: '+14155552671', email_address: 'jane.smith@example.com', address: { street: '500 Market St', city: 'San Francisco', region: 'CA', postal_code: '94105', country: 'US', }, }, }; try { const response = await plaidClient.identityMatch(request); const accounts = response.data.accounts; for (const account of accounts) { const legalNameScore = account.legal_name?.score; const phoneScore = account.phone_number?.score; const emailScore = account.email_address?.score; const addressScore = account.address?.score; } } catch (error) { // handle error } ``` ```java // Omit user object if using Identity Verification / Financial Account Matching IdentityMatchUser user = new IdentityMatchUser() .legalName("Jane Smith") .phoneNumber("+14155552671") .emailAddress("jane.smith@example.com") .address(new AddressDataNullableNoRequiredFields() .street("500 Market St") .city("San Francisco") .region("CA") .postalCode("94105") .country("US")); IdentityMatchRequest request = new IdentityMatchRequest() .accessToken(accessToken) .user(user); Response response = plaidClient.service().identityMatch(request).execute(); List accounts = response.body().getAccounts(); for (IdentityMatchResponse.AccountIdentityMatchScores account : accounts) { Integer legalNameScore = account.getLegalName() != null ? account.getLegalName().getScore() : null; Integer phoneNumberScore = account.getPhoneNumber() != null ? account.getPhoneNumber().getScore() : null; Integer emailAddressScore = account.getEmailAddress() != null ? account.getEmailAddress().getScore() : null; Integer addressScore = account.getAddress() != null ? account.getAddress().getScore() : null; // Compare scores to risk thresholds } ``` ```python # Omit user object if using Identity Verification / Financial Account Matching user = IdentityMatchUser( legal_name="Jane Smith", phone_number="+14155552671", email_address="jane.smith@example.com", address=AddressDataNullableNoRequiredFields( street="500 Market St", city="San Francisco", region="CA", postal_code="94105", country="US" ) ) request = IdentityMatchRequest( access_token=access_token, user=user ) response = client.identity_match(request) accounts = response['accounts'] for account in accounts: name_score = account['legal_name']['score'] if account['legal_name'] is not None else None phone_score = account['phone_number']['score'] if account['phone_number'] is not None else None email_score = account['email_address']['score'] if account['email_address'] is not None else None address_score = account['address']['score'] if account['address'] is not None else None ``` ```go // Omit user object if using Identity Verification / Financial Account Matching user := plaid.IdentityMatchUser{} user.SetLegalName("Jane Smith") user.SetPhoneNumber("+14155552671") user.SetEmailAddress("jane.smith@example.com") address := plaid.AddressDataNullableNoRequiredFields{} address.SetStreet("500 Market St") address.SetCity("San Francisco") address.SetRegion("CA") address.SetPostalCode("94105") address.SetCountry("US") user.SetAddress(address) request := plaid.NewIdentityMatchRequest(accessToken) request.SetUser(user) response, _, err := client.PlaidApi.IdentityMatch(ctx).IdentityMatchRequest(*request).Execute() if err != nil { log.Fatal(err) } accounts := response.GetAccounts() for _, account := range accounts { if legalName, ok := account.GetLegalNameOk(); ok { legalNameScore := legalName.GetScore() _ = legalNameScore } if phoneNumber, ok := account.GetPhoneNumberOk(); ok { phoneScore := phoneNumber.GetScore() _ = phoneScore } if emailAddress, ok := account.GetEmailAddressOk(); ok { emailScore := emailAddress.GetScore() _ = emailScore } if address, ok := account.GetAddressOk(); ok { addressScore := address.GetScore() _ = addressScore } } ``` #### Response fields  \[object\] The accounts for which Identity match has been requested string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` nullable, object Score found by matching name provided by the API with the name on the account at the financial institution. If the account contains multiple owners, the maximum match score is filled. nullable, integer Match score for name. 100 is a perfect score, 99-85 means a strong match, 84-70 is a partial match, any score less than 70 is a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the name is missing from either the API or financial institution, this is null. nullable, boolean first or last name completely matched, likely a family member nullable, boolean nickname matched, example Jennifer and Jenn. nullable, boolean Is `true` if the name on either of the names that was matched for the score contained strings indicative of a business name, such as "CORP", "LLC", "INC", or "LTD". A `true` result generally indicates that an account's name is a business name. However, a `false` result does not mean the account name is not a business name, as some businesses do not use these strings in the names used for their financial institution accounts. nullable, object Score found by matching phone number provided by the API with the phone number on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled. nullable, integer Match score for normalized phone number. 100 is a perfect match, 99-70 is a partial match (matching the same phone number with extension against one without extension, etc.), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the phone number is missing from either the API or financial institution, this is null. nullable, object Score found by matching email provided by the API with the email on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled. nullable, integer Match score for normalized email. 100 is a perfect match, 99-70 is a partial match (matching the same email with different '+' extensions), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the email is missing from either the API or financial institution, this is null. nullable, object Score found by matching address provided by the API with the address on the account at the financial institution. The score can range from 0 to 100 where 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled. nullable, integer Match score for address. 100 is a perfect match, 99-90 is a strong match, 89-70 is a partial match, anything below 70 is considered a weak match. Typically, the match threshold should be set to a score of 70 or higher. If the address is missing from either the API or financial institution, this is null. nullable, boolean postal code was provided for both and was a match object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "accounts": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": null, "current": null, "iso_currency_code": null, "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "legal_name": { "score": 90, "is_nickname_match": true, "is_first_name_or_last_name_match": true, "is_business_name_detected": false }, "phone_number": { "score": 100 }, "email_address": { "score": 100 }, "address": { "score": 100, "is_postal_code_match": true }, "subtype": "checking", "type": "depository" }, { "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "balances": { "available": null, "current": null, "iso_currency_code": null, "limit": null, "unofficial_currency_code": null }, "mask": "1111", "name": "Plaid Saving", "official_name": "Plaid Silver Standard 0.1% Interest Saving", "legal_name": { "score": 30, "is_first_name_or_last_name_match": false }, "phone_number": { "score": 100 }, "email_address": null, "address": { "score": 100, "is_postal_code_match": true }, "subtype": "savings", "type": "depository" } ], "item": { "available_products": [ "balance", "investments" ], "billed_products": [ "assets", "auth", "identity", "liabilities", "transactions" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_3", "institution_name": "Chase", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook", "auth_method": "INSTANT_AUTH" }, "request_id": "3nARps6TOYtbACO" } ``` \=\*=\*=\*= #### /identity/documents/uploads/get  #### Returns uploaded document identity  Use [/identity/documents/uploads/get](https://plaid.com/docs/api/products/identity/index.html.md#identitydocumentsuploadsget) to retrieve identity details when using [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. object An optional object to filter `/identity/documents/uploads/get` results. \[string\] A list of `account_ids` to retrieve for the Item. Note: An error will be returned if a provided `account_id` is not associated with the Item. ```node const request: IdentityDocumentsUploadsGetRequest = { access_token: accessToken, }; try { const response = await client.identityDocumentsUploadsGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/identity/documents/uploads/get \ -H 'Content-Type: application/json' \ -d '{ "access_token": String, "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}" }' ``` ```ruby request = Plaid::IdentityDocumentsUploadsGetRequest.new( { access_token: access_token } ) response = client.identity_documents_uploads_get(request) ``` ```java IdentityDocumentsUploadsGetRequest request = new IdentityDocumentsUploadsGetRequest() .accessToken(accessToken); Response response = client() .identityDocumentsUploadsGet(request) .execute(); ``` ```python request = IdentityDocumentsUploadsGetRequest( access_token=access_token ) response = client.identity_documents_uploads_get(request) ``` ```go request := plaid.NewIdentityDocumentsUploadsGetRequest( accessToken, ) response, _, err := client.PlaidApi. IdentityDocumentsUploadsGet(ctx). IdentityDocumentsUploadsGetRequest(*request). Execute() ``` #### Response fields  \[object\] The accounts for which Identity data has been requested string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution; detecting whether the linked account is a business account is not currently supported. Multiple owners on a single account will be represented in the same `owner` object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the `owners` object is not returned, and instead identity information is returned in the top level `identity` object. For more details, see [Plaid API versioning](https://plaid.com/docs/api/versioning/index.html.md#version-2019-05-29) \[string\] A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's `names` array. \[object\] A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The phone number. boolean When `true`, identifies the phone number as the primary number on an account. string The type of phone number. Possible values: `home`, `work`, `office`, `mobile`, `mobile1`, `other` \[object\] A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The email address. boolean When `true`, identifies the email address as the primary email on an account. string The type of email account as described by the financial institution. Possible values: `primary`, `secondary`, `other` \[object\] Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. object Data about the components comprising an address. nullable, string The full city name nullable, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code boolean When `true`, identifies the address as the primary address on an account. nullable, \[object\] Data about the documents that were uploaded as proof of account ownership. string A UUID identifying the document. object Metadata pertaining to the document. nullable, string The submitted document type. Currently, this will always be `BANK_STATEMENT`. nullable, boolean Boolean field indicating whether the uploaded document's account number matches the account number we have on file. If `false`, it is not recommended to accept the uploaded identity data as accurate without further verification. nullable, integer The number of pages in the uploaded document. string The timestamp when the document was last updated. Format: `date-time` string The timestamp when the document was originally uploaded. Format: `date-time` object Object representing fraud risk data of the uploaded document. Only provided when using Identity Document Upload with Fraud Risk enabled. object Risk summary of an uploaded document. nullable, integer A number between 0 and 100, inclusive, where a score closer to 0 indicates a document is likely to be trustworthy and a score closer to 100 indicates a document is likely to be fraudulent. \[object\] An array of risk signals. nullable, string The type of risk found. Possible values: `FONT`, `MASKING`, `OVERLAID_TEXT`, `EDITED_TEXT`, `TEXT_COMPRESSION`, `ADDRESS_FORMAT_ANOMALY`, `DATE_FORMAT_ANOMALY`, `FONT_ANOMALY`, `NAME_FORMAT_ANOMALY`, `PDF_ALIGNMENT`, `BRUSH_DETECTION`, `METADATA_DATES_OUTSIDE_WINDOW`, `METADATA_DATES_INSIDE_WINDOW`, `METADATA_DATES_MISSING`, `METADATA_DATES_MATCH`, `ADOBE_FONTS`, `ANNOTATION_DATES`, `ANNOTATIONS`, `EDITED_WHILE_SCANNED`, `EXIF_DATA_MODIFIED`, `HIGH_USER_ACCESS`, `MALFORMED_DATE`, `QPDF`, `TEXT_LAYER_TEXT`, `TOUCHUP_TEXT`, `FLATTENED_PDF`, `BLACKLISTS`, `COPYCAT_IMAGE`, `COPYCAT_TEXT`, `REJECTED_CUSTOMER`, `TEMPLATES`, `SOFTWARE_BLACKLIST` nullable, boolean Indicates whether fraud risk was detected on the field. nullable, string A human-readable explanation providing more detail about the specific risk signal. nullable, integer The relevant page associated with the risk signal. If the risk signal is not associated with a specific page, the value will be 0. object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "accounts": [ { "account_id": "ZXEbW7Rkr9iv1qj8abebU1KDMlkexgSgrLAod", "balances": { "available": null, "current": null, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "documents": [ { "document_id": "9f838fef-b0a5-4ef4-bf73-8e5248d43ad7", "metadata": { "document_type": "BANK_STATEMENT", "is_account_number_match": true, "last_updated": "2024-09-25T23:57:12Z", "page_count": 1, "uploaded_at": "2024-09-25T23:57:12Z" }, "risk_insights": { "risk_signals": [ { "has_fraud_risk": true, "page_number": 0, "signal_description": "Creation date and modification date do not match", "type": "METADATA_DATES_OUTSIDE_WINDOW" }, { "has_fraud_risk": true, "page_number": 0, "signal_description": "Adobe Acrobat", "type": "SOFTWARE_BLACKLIST" } ], "risk_summary": { "risk_score": 100 } } } ], "mask": "0000", "name": "Checking ...0000", "official_name": null, "owners": [ { "addresses": [ { "data": { "city": "OAKLAND", "country": "US", "postal_code": "94103", "region": "CA", "street": "1234 GRAND AVE" }, "primary": true } ], "document_id": "9f838fef-b0a5-4ef4-bf73-8e5248d43ad7", "emails": [], "names": [ "JANE DOE" ], "phone_numbers": [] } ], "subtype": "checking", "type": "depository", "verification_status": "manually_verified" } ], "item": { "available_products": [], "billed_products": [ "auth" ], "consent_expiration_time": null, "error": null, "item_id": "QwpzDByRv8uvdpwKEW3WU4PkGEApajtp3o4NN", "products": [ "auth" ], "update_type": "background", "webhook": "https://www.example.com/webhook" }, "request_id": "b5jvmskusjwX5Gs" } ``` ### Webhooks (beta)  This feature is in currently in beta; please reach out to your Plaid account manager if you would like it enabled. \=\*=\*=\*= #### DEFAULT\_UPDATE  Fired when a change to identity data has been detected on an Item. Items are checked for identity updates every 30-90 days. We recommend that upon receiving this webhook you make another call to [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) to fetch the user's latest identity data. #### Properties  string `IDENTITY` string `DEFAULT_UPDATE` string The `item_id` of the Item associated with this webhook, warning, or error object An object with keys of `account_id`'s that are mapped to their respective identity attributes that changed. Example: `{ "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": ["PHONES"] }` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "IDENTITY", "webhook_code": "DEFAULT_UPDATE", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "account_ids_with_updated_identity": { "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp": [ "ADDRESSES" ] }, "error": null, "environment": "production" } ``` --- # API - Income | Plaid Docs Income  ======= #### API reference for Income endpoints and webhooks  Verify a user's income via payroll or bank account data. For how-to guidance, see the [Income documentation](https://plaid.com/docs/income/index.html.md) . | Endpoints | | | --- | --- | | [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) | Get Link session metadata and results for the end user | | [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) | Retrieve information from the bank accounts used for income verification | | [/credit/bank\_income/pdf/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomepdfget) | Retrieve information from the bank accounts used for income verification in PDF format | | [/credit/bank\_statements/uploads/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_statementsuploadsget) | Retrieve information from the bank statements used for income verification | | [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) | Retrieve information from the pay stubs or tax forms used for income verification | | [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) | Analyze uploaded income documents for indications of potential fraud | | [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) | Update the parsing configuration for a document verification | | [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) | (beta) Retrieve employment information about the end user | | [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) | (beta) Retrieve updated payroll income data on a linked account | | See also | | | --- | --- | | [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) | Manually fire an Income webhook (Sandbox only) | | [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) | Create a user for use with the income verification product | | Webhooks | | | --- | --- | | [INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) | Income verification has completed | | [INCOME\_VERIFICATION\_RISK\_SIGNALS](https://plaid.com/docs/api/products/income/index.html.md#income_verification_risk_signals) | Risk evaluation of user-uploaded documents has completed | | [BANK\_INCOME\_REFRESH\_COMPLETE](https://plaid.com/docs/api/products/income/index.html.md#bank_income_refresh_complete) | The refreshed report has finished generating | | [INCOME\_VERIFICATION\_REFRESH\_RECONNECT\_NEEDED](https://plaid.com/docs/api/products/income/index.html.md#income_verification_refresh_reconnect_needed) | A Payroll Income verification could not be refreshed | ### Endpoints  \=\*=\*=\*= #### /user/create  #### Create user  For Plaid products and flows that use the user object, [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) provides you a single token to access all data associated with the user. You must call this endpoint before calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) if you are using any of the following: Plaid Check, Income Verification, Multi-Item Link, or Plaid Protect (Identity). If you are using Plaid Protect Link session scoring, you do not need to call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) first; Plaid will resolve or create the user when `user.client_user_id` is provided in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . For customers who began using this endpoint on or after December 10, 2025, this endpoint takes a `client_user_id` and an `identity` object and will return a `user_id`. For customers who began using it before that date, the endpoint takes a `client_user_id` and a `consumer_report_user_identity` object and will return a `user_token` and `user_id`. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . In order to create a Plaid Check Consumer Report for a user, the `identity` (new) or `consumer_report_user_identity` (legacy) object must be present. If it is not provided during the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) call, it can be added later by calling [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) . In order to generate a Plaid Check Consumer Report, the following `identity` fields, at minimum, are required and must be non-empty: `name`, `date_of_birth`, `emails`, `phone_numbers`, and `addresses`, (with at least one email, phone number, and address designated as `primary`). Plaid Check Consumer Reports can only be created for US-based users; the user's address country must be `US`. If creating a report for sharing with a GSE such as Fannie or Freddie, the user's full SSN must be provided via the `id_numbers` field. Providing at least a partial SSN is also strongly recommended for all use cases, since it improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. When using Plaid Protect, it is highly recommended that you provide an `identity` object to better identify and block fraud across your Link sessions. Plaid will normalize identity fields before storing them and utilize the same identity across different user-based products. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string A unique ID representing the end user. Maximum of 128 characters. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. Max length: `128` Min length: `1` object The identity fields associated with a user. For a user to be eligible for a Plaid Check Consumer Report, all fields are required except `id_number`. Providing a partial SSN is strongly recommended, and improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. If creating a report that will be shared with GSEs such as Fannie or Freddie, a full Social Security Number must be provided via the `id_number` field. object User name information. required, string User's given name. required, string User's family name. string The user's date of birth, to be provided in the format "yyyy-mm-dd". Format: `date` \[object\] The user's emails. required, string User's email. required, boolean Indicates whether this is the primary email for the User. \[object\] The user's phone numbers, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. required, string User's phone number. required, boolean Indicates whether this is the primary phone number for the User. \[object\] The user's addresses. string First line of street address. string Second line of street address. string City name. string State, province or region. required, string Country code. string Postal or ZIP code. required, boolean Indicates whether this is the primary address for the User. \[object\] The user's ID numbers. required, string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . required, string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` object This field is only used by integrations created before December 10, 2025. All other integrations must use the `identity` object instead. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . To create a Plaid Check Consumer Report for a user when using a `user_token`, this field must be present. If this field is not provided during user token creation, you can add it to the user later by calling `/user/update`. Once the field has been added to the user, you will be able to call `/link/token/create` with a non-empty `consumer_report_permissible_purpose` (which will automatically create a Plaid Check Consumer Report), or call `/cra/check_report/create` for that user. required, string The user's first name required, string The user's last name required, \[string\] The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. required, \[string\] The user's emails string The user's full social security number. This field should only be provided by lenders intending to share the resulting consumer report with a Government-Sponsored Enterprise (GSE), such as Fannie Mae or Freddie Mac. Format: "ddd-dd-dddd" string The last 4 digits of the user's social security number. Max length: `4` Min length: `4` required, string To be provided in the format "yyyy-mm-dd". This field is required for all Plaid Check customers. Format: `date` required, object Data about the components comprising an address. required, string The full city name required, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` required, string The full street address Example: `"564 Main Street, APT 15"` required, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. required, string The ISO 3166-1 alpha-2 country code boolean If your integration with the User API predates December 10, 2025, set this field to `true` to opt into the [new User API](https://plaid.com/docs/api/users/user-apis/index.html.md) . When enabled, you can use the `identity` field instead of `consumer_report_user_identity`. ```node const request: UserCreateRequest = { client_user_id: 'c0e2c4ee-b763-4af5-cfe9-46a46bce883d', }; try { const response = await client.userCreate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/user/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_user_id": "c0e2c4ee-b763-4af5-cfe9-46a46bce883d" }' ``` ```ruby request = Plaid::UserCreateRequest.new( { client_user_id: 'c0e2c4ee-b763-4af5-cfe9-46a46bce883d' } ) response = client.user_create(request) ``` ```java UserCreateRequest request = new UserCreateRequest() .clientUserId("c0e2c4ee-b763-4af5-cfe9-46a46bce883d"); Response response = client .userCreate(request) .execute(); ``` ```python request = UserCreateRequest( client_user_id='c0e2c4ee-b763-4af5-cfe9-46a46bce883d' ) response = client.user_create(request) ``` ```go request := plaid.NewUserCreateRequest( "c0e2c4ee-b763-4af5-cfe9-46a46bce883d", ) response, _, err := client.PlaidApi.UserCreate(ctx).UserCreateRequest(*request).Execute() ``` #### Response fields  string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "user_id": "usr_9nSp2KuZ2x4JDw", "request_id": "Aim3b" } ``` \=\*=\*=\*= #### /credit/sessions/get  #### Retrieve Link sessions for your user  This endpoint can be used for your end users after they complete the Link flow. This endpoint returns a list of Link sessions that your user completed, where each session includes the results from the Link flow. These results include details about the Item that was created and some product related metadata (showing, for example, whether the user finished the bank income verification step). #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```node const request: CreditSessionsGetRequest = { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', }; try { const response = await client.creditSessionsGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/credit/sessions/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" }' ``` ```ruby request = Plaid::CreditSessionsGetRequest.new( { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' } ) response = client.credit_sessions_get(request) ``` ```java CreditSessionsGetRequest request = new CreditSessionsGetRequest() .userToken("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"); Response response = client .creditSessionsGet(request) .execute(); ``` ```python request = CreditSessionsGetRequest( user_token='user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' ) response = client.credit_sessions_get(request) ``` ```go request := plaid.NewCreditSessionsGetRequest( "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", ) response, _, err := client.PlaidApi.CreditSessionsGet(ctx).CreditSessionsGetRequest(*request).Execute() ``` #### Response fields  \[object\] A list of Link sessions for the user. Sessions will be sorted in reverse chronological order. string The unique identifier associated with the Link session. This identifier matches the `link_session_id` returned in the onSuccess/onExit callbacks. string The time when the Link session started Format: `date-time` object The set of results for a Link session. \[object\] The set of Item adds for the Link session. string Returned once a user has successfully linked their Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. string The Plaid Institution ID associated with the Item. \[object\] The set of bank income verifications for the Link session. string Status of the Bank Income Link session. `APPROVED`: User has approved and verified their income `NO_DEPOSITS_FOUND`: We attempted, but were unable to find any income in the connected account. `USER_REPORTED_NO_INCOME`: The user explicitly indicated that they don't receive income in the connected account. `STARTED`: The user began the bank income portion of the link flow. `INTERNAL_ERROR`: The user encountered an internal error. Possible values: `APPROVED`, `NO_DEPOSITS_FOUND`, `USER_REPORTED_NO_INCOME` string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. string The Plaid Institution ID associated with the Item. \[object\] The set of bank employment verifications for the Link session. string Status of the Bank Employment Link session. `APPROVED`: User has approved and verified their employment. `NO_EMPLOYMENTS_FOUND`: We attempted, but were unable to find any employment in the connected account. `EMPLOYER_NOT_LISTED`: The user explicitly indicated that they did not see their current or previous employer in the list of employer names found. `STARTED`: The user began the bank income portion of the link flow. `INTERNAL_ERROR`: The user encountered an internal error. Possible values: `APPROVED`, `NO_EMPLOYERS_FOUND`, `EMPLOYER_NOT_LISTED` string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. string The Plaid Institution ID associated with the Item. \[object\] The set of payroll income verifications for the Link session. integer The number of paystubs retrieved from a payroll provider. integer The number of w2s retrieved from a payroll provider. string The Plaid Institution ID associated with the Item. string The Institution Name associated with the Item. nullable, object The details of a document income verification in Link integer The number of paystubs uploaded by the user. integer The number of w2s uploaded by the user. integer The number of bank statements uploaded by the user. integer The number of 1099s uploaded by the user \[object\] The set of errors that occurred during the Link session. string A broad categorization of the error. string The particular error code. string A developer-friendly representation of the error code. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "Aim3b", "sessions": [ { "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171", "results": { "item_add_results": [ { "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc", "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op", "institution_id": "ins_56" } ], "bank_income_results": [ { "status": "APPROVED", "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op", "institution_id": "ins_56" } ] }, "session_start_time": "2022-09-30T23:40:30.946225Z" }, { "link_session_id": "f742cae8-31e4-49cc-a621-6cafbdb26fb9", "results": { "payroll_income_results": [ { "num_paystubs_retrieved": 2, "num_w2s_retrieved": 1, "institution_id": "ins_92" } ] }, "session_start_time": "2022-09-26T23:40:30.946225Z" } ] } ``` \=\*=\*=\*= #### /credit/bank\_income/get  #### Retrieve information from the bank accounts used for income verification  [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) returns the bank income report(s) for a specified user. A single report corresponds to all institutions linked in a single Link session. To include multiple institutions in a single report, use [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) . To return older reports, use the `options.count` field. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . object An optional object for `/credit/bank_income/get` request options. integer How many Bank Income Reports should be fetched. Multiple reports may be available if the report has been re-created or refreshed. If more than one report is available, the most recent reports will be returned first. Default: `1` ```node const request: CreditBankIncomeGetRequest = { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', options: { count: 1, }, }; try { const response = await client.creditBankIncomeGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/credit/bank_income/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", "options": { "count": 1 } }' ``` ```ruby request = Plaid::CreditBankIncomeGetRequest.new( { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', options: { count: 1 } } ) response = client.credit_bank_income_get(request) ``` ```java CreditBankIncomeGetRequestOptions options = new CreditBankIncomeGetRequestOptions() .count(1); CreditBankIncomeGetRequest request = new CreditBankIncomeGetRequest() .userToken("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d") .options(options); Response response = client .creditBankIncomeGet(request) .execute(); ``` ```python request = CreditBankIncomeGetRequest( user_token='user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', options=CreditBankIncomeGetRequestOptions( count=1 ) ) response = client.credit_bank_income_get(request) ``` ```go request := plaid.NewCreditBankIncomeGetRequest( "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", *plaid.NewCreditBankIncomeGetRequestOptions( 1, ) ) response, _, err := client.PlaidApi.CreditBankIncomeGet(ctx).CreditBankIncomeGetRequest(*request).Execute() ``` #### Response fields  \[object\] string The unique identifier associated with the Bank Income Report. string The time when the report was generated. Format: `date-time` integer The number of days requested by the customer for the report. \[object\] The list of Items in the report along with the associated metadata about the Item. \[object\] The Item's accounts that have Bank Income data. string Plaid's unique identifier for the account. nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user. string The name of the bank account. nullable, string The official name of the bank account. string Valid account subtypes for depository accounts. For a list containing descriptions of each subtype, see [Account schemas](https://plaid.com/docs/api/accounts/index.html.md#StandaloneAccountType-depository) . Possible values: `checking`, `savings`, `hsa`, `cd`, `money market`, `paypal`, `prepaid`, `cash management`, `ebt`, `limited purpose checking`, `all` string The account type. This will always be `depository`. Possible values: `depository` \[object\] Data returned by the financial institution about the account owner or owners. Identity information is optional, so field may return an empty array. \[string\] A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's `names` array. \[object\] A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The phone number. boolean When `true`, identifies the phone number as the primary number on an account. string The type of phone number. Possible values: `home`, `work`, `office`, `mobile`, `mobile1`, `other` \[object\] A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. string The email address. boolean When `true`, identifies the email address as the primary email on an account. string The type of email account as described by the financial institution. Possible values: `primary`, `secondary`, `other` \[object\] Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution. object Data about the components comprising an address. nullable, string The full city name nullable, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code boolean When `true`, identifies the address as the primary address on an account. \[object\] The income sources for this Item. Each entry in the array is a single income source. string A unique identifier for an income source. string The most common name or original description for the underlying income transactions. string The income category. `BANK_INTEREST`: Interest earned from a bank account. `BENEFIT_OTHER`: Government benefits other than retirement, unemployment, child support, or disability. Currently used only in the UK, to represent benefits such as Cost of Living Payments. `CASH`: Deprecated and used only for existing legacy implementations. Has been replaced by `CASH_DEPOSIT` and `TRANSFER_FROM_APPLICATION`. `CASH_DEPOSIT`: A cash or check deposit. `CHILD_SUPPORT`: Child support payments received. `GIG_ECONOMY`: Income earned as a gig economy worker, e.g. driving for Uber, Lyft, Postmates, DoorDash, etc. `LONG_TERM_DISABILITY`: Disability payments, including Social Security disability benefits. `OTHER`: Income that could not be categorized as any other income category. `MILITARY`: Veterans benefits. Income earned as salary for serving in the military (e.g. through DFAS) will be classified as `SALARY` rather than `MILITARY`. `RENTAL`: Income earned from a rental property. Income may be identified as rental when the payment is received through a rental platform, e.g. Airbnb; rent paid directly by the tenant to the property owner (e.g. via cash, check, or ACH) will typically not be classified as rental income. `RETIREMENT`: Payments from private retirement systems, pensions, and government retirement programs, including Social Security retirement benefits. `SALARY`: Payment from an employer to an earner or other form of permanent employment. `TAX_REFUND`: A tax refund. `TRANSFER_FROM_APPLICATION`: Deposits from a money transfer app, such as Venmo, Cash App, or Zelle. `UNEMPLOYMENT`: Unemployment benefits. In the UK, includes certain low-income benefits such as the Universal Credit. Possible values: `SALARY`, `UNEMPLOYMENT`, `CASH`, `GIG_ECONOMY`, `RENTAL`, `CHILD_SUPPORT`, `MILITARY`, `RETIREMENT`, `LONG_TERM_DISABILITY`, `BANK_INTEREST`, `CASH_DEPOSIT`, `TRANSFER_FROM_APPLICATION`, `TAX_REFUND`, `BENEFIT_OTHER`, `OTHER` string Plaid's unique identifier for the account. string Minimum of all dates within the specific income sources in the user's bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string Maximum of all dates within the specific income sources in the user’s bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The income pay frequency. Possible values: `WEEKLY`, `BIWEEKLY`, `SEMI_MONTHLY`, `MONTHLY`, `DAILY`, `UNKNOWN` number Total amount of earnings in the user’s bank account for the specific income source for days requested by the client. integer Number of transactions for the income source within the start and end date. \[object\] deprecated, number Total amount of earnings for the income source(s) of the user for the month in the summary. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use [total\_amounts](https://plaid.com/docs/api/products/income/index.html.md#credit-bank_income-get-response-bank-income-items-bank-income-sources-historical-summary-total-amounts) instead. deprecated, nullable, string The ISO 4217 currency code of the amount or balance. Please use [total\_amounts](https://plaid.com/docs/api/products/income/index.html.md#credit-bank_income-get-response-bank-income-items-bank-income-sources-historical-summary-total-amounts) instead. deprecated, nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. Please use [total\_amounts](https://plaid.com/docs/api/products/income/index.html.md#credit-bank_income-get-response-bank-income-items-bank-income-sources-historical-summary-total-amounts) instead. \[object\] Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. string The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` \[object\] number The settled value of the transaction, denominated in the transactions's currency as stated in `iso_currency_code` or `unofficial_currency_code`. Positive values when money moves out of the account; negative values when money moves in. For example, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The merchant name or transaction description. nullable, string The string returned by the financial institution to describe the transaction. boolean When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. nullable, string The check number of the transaction. This field is only populated for check transactions. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. string The time when this Item's data was last retrieved from the financial institution. Format: `date-time` string The unique identifier of the institution associated with the Item. string The name of the institution associated with the Item. string The unique identifier for the Item. object Summary for bank income across all income sources and items (max history of 730 days). deprecated, number Total amount of earnings across all the income sources in the end user's Items for the days requested by the client. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use [total\_amounts](https://plaid.com/docs/api/products/income/index.html.md#credit-bank_income-get-response-bank-income-bank-income-summary-total-amounts) instead. deprecated, nullable, string The ISO 4217 currency code of the amount or balance. Please use [total\_amounts](https://plaid.com/docs/api/products/income/index.html.md#credit-bank_income-get-response-bank-income-bank-income-summary-total-amounts) instead. deprecated, nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. Please use [total\_amounts](https://plaid.com/docs/api/products/income/index.html.md#credit-bank_income-get-response-bank-income-bank-income-summary-total-amounts) instead. \[object\] Total amount of earnings across all the income sources in the end user's Items for the days requested by the client. This can contain multiple amounts, with each amount denominated in one unique currency. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. string The earliest date within the days requested in which all income sources identified by Plaid appear in a user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The latest date in which all income sources identified by Plaid appear in the user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` integer Number of income sources per end user. integer Number of income categories per end user. integer Number of income transactions per end user. \[object\] deprecated, number Total amount of earnings for the income source(s) of the user for the month in the summary. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use [total\_amounts](https://plaid.com/docs/api/products/income/index.html.md#credit-bank_income-get-response-bank-income-items-bank-income-sources-historical-summary-total-amounts) instead. deprecated, nullable, string The ISO 4217 currency code of the amount or balance. Please use [total\_amounts](https://plaid.com/docs/api/products/income/index.html.md#credit-bank_income-get-response-bank-income-items-bank-income-sources-historical-summary-total-amounts) instead. deprecated, nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. Please use [total\_amounts](https://plaid.com/docs/api/products/income/index.html.md#credit-bank_income-get-response-bank-income-items-bank-income-sources-historical-summary-total-amounts) instead. \[object\] Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency. number Value of amount with up to 2 decimal places. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. string The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` \[object\] number The settled value of the transaction, denominated in the transactions's currency as stated in `iso_currency_code` or `unofficial_currency_code`. Positive values when money moves out of the account; negative values when money moves in. For example, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format (YYYY-MM-DD). Format: `date` string The merchant name or transaction description. nullable, string The string returned by the financial institution to describe the transaction. boolean When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. nullable, string The check number of the transaction. This field is only populated for check transactions. nullable, string The ISO 4217 currency code of the amount or balance. nullable, string The unofficial currency code associated with the amount or balance. Always `null` if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. \[object\] If data from the report was unable to be retrieved, the warnings will contain information about the error that caused the data to be incomplete. string The warning type which will always be `BANK_INCOME_WARNING`. Possible values: `BANK_INCOME_WARNING` string The warning code identifies a specific kind of warning. `IDENTITY_UNAVAILABLE`: Unable to extract identity for the Item `TRANSACTIONS_UNAVAILABLE`: Unable to extract transactions for the Item `ITEM_UNAPPROVED`: User exited flow before giving permission to share data for the Item `REPORT_DELETED`: Report deleted due to customer or consumer request `DATA_UNAVAILABLE`: No relevant data was found for the Item Possible values: `IDENTITY_UNAVAILABLE`, `TRANSACTIONS_UNAVAILABLE`, `ITEM_UNAPPROVED`, `REPORT_DELETED`, `DATA_UNAVAILABLE` object An error object and associated `item_id` used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items. string A broad categorization of the error. Safe for programmatic use. Possible values: `INTERNAL_SERVER_ERROR`, `INSUFFICIENT_CREDENTIALS`, `ITEM_LOCKED`, `USER_SETUP_REQUIRED`, `COUNTRY_NOT_SUPPORTED`, `INSTITUTION_DOWN`, `INSTITUTION_NO_LONGER_SUPPORTED`, `INSTITUTION_NOT_RESPONDING`, `INVALID_CREDENTIALS`, `INVALID_MFA`, `INVALID_SEND_METHOD`, `ITEM_LOGIN_REQUIRED`, `MFA_NOT_SUPPORTED`, `NO_ACCOUNTS`, `ITEM_NOT_SUPPORTED`, `ACCESS_NOT_GRANTED` string We use standard HTTP response codes for success and failure notifications, and our errors are further classified by `error_type`. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. Error fields will be `null` if no error has occurred. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use. string The `item_id` of the Item associated with this warning. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "bank_income": [ { "bank_income_id": "dacc92a0-cb59-43a5-ba24-1b1c07a03f28", "bank_income_summary": { "end_date": "2024-08-21", "historical_summary": [ { "end_date": "2024-08-21", "iso_currency_code": "USD", "start_date": "2024-08-06", "total_amount": 4090.14, "total_amounts": [ { "amount": 4090.14, "iso_currency_code": "USD", "unofficial_currency_code": null } ], "transactions": [ { "amount": 120.12, "check_number": null, "date": "2024-08-07", "iso_currency_code": "USD", "name": "TEXAS OAG CHILD SUPPORT", "original_description": "TEXAS OAG CHILD SUPPORT", "transaction_id": "EZMmvwREqlSGmlRam7bzFKyBll3kJjU4xKm1w", "unofficial_currency_code": null }, { "amount": 1525, "check_number": null, "date": "2024-08-08", "iso_currency_code": "USD", "name": "AIRBNB PAYMENTS PPD ID: 1234567890", "original_description": "AIRBNB PAYMENTS PPD ID: 1234567890", "transaction_id": "Wr6jzLwg1qs6ag9Xa8BrCpBAPPxnEXF6ZmjDR", "unofficial_currency_code": null }, { "amount": 500, "check_number": null, "date": "2024-08-12", "iso_currency_code": "USD", "name": "TWC-BENEFITS/UI BENEFIT", "original_description": "TWC-BENEFITS/UI BENEFIT", "transaction_id": "Aj7Apx5bDyIA3VRl35yqC18wXXorBgI9rX5dp", "unofficial_currency_code": null }, { "amount": 1000.7, "check_number": null, "date": "2024-08-15", "iso_currency_code": "USD", "name": "PLAID PAYROLL", "original_description": "PLAID PAYROLL", "transaction_id": "G1L9oybBrKSMPmBdPzXoFN8aGGE7gXC6MeoQB", "unofficial_currency_code": null }, { "amount": 824.2, "check_number": null, "date": "2024-08-15", "iso_currency_code": "USD", "name": "SSI TREAS 310 XXSUPP SEC PPD ID: 1234567890", "original_description": "SSI TREAS 310 XXSUPP SEC PPD ID: 1234567890", "transaction_id": "nWLlwMm1qxi8DomvDXP3FaGjXX5bm9TAlyQnk", "unofficial_currency_code": null }, { "amount": 120.12, "check_number": null, "date": "2024-08-21", "iso_currency_code": "USD", "name": "TEXAS OAG CHILD SUPPORT", "original_description": "TEXAS OAG CHILD SUPPORT", "transaction_id": "b7dkg6eQbPFQeRvVeZlxcqxZooa7nWSmb47dj", "unofficial_currency_code": null } ], "unofficial_currency_code": null } ], "income_categories_count": 5, "income_sources_count": 5, "income_transactions_count": 6, "iso_currency_code": "USD", "start_date": "2024-08-07", "total_amount": 4090.14, "total_amounts": [ { "amount": 4090.14, "iso_currency_code": "USD", "unofficial_currency_code": null } ], "unofficial_currency_code": null }, "days_requested": 15, "generated_time": "2024-08-21T18:10:46.293199Z", "items": [ { "bank_income_accounts": [ { "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5", "mask": "9217", "name": "Checking", "official_name": "Plaid checking", "owners": [ { "addresses": [], "emails": [], "names": [ "Jane Doe" ], "phone_numbers": [] } ], "subtype": "checking", "type": "depository" } ], "bank_income_sources": [ { "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5", "end_date": "2024-08-15", "historical_summary": [ { "end_date": "2024-08-21", "iso_currency_code": "USD", "start_date": "2024-08-06", "total_amount": 1000.7, "total_amounts": [ { "amount": 1000.7, "iso_currency_code": "USD", "unofficial_currency_code": null } ], "transactions": [ { "amount": 1000.7, "check_number": null, "date": "2024-08-15", "iso_currency_code": "USD", "name": "PLAID PAYROLL", "original_description": "PLAID PAYROLL", "transaction_id": "G1L9oybBrKSMPmBdPzXoFN8aGGE7gXC6MeoQB", "unofficial_currency_code": null } ], "unofficial_currency_code": null } ], "income_category": "SALARY", "income_description": "PLAID PAYROLL", "income_source_id": "0e9d6fbc-29de-4225-9843-2f71e02a54d1", "pay_frequency": "UNKNOWN", "start_date": "2024-08-15", "total_amount": 1000.7, "transaction_count": 1 }, { "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5", "end_date": "2024-08-15", "historical_summary": [ { "end_date": "2024-08-21", "iso_currency_code": "USD", "start_date": "2024-08-06", "total_amount": 824.2, "total_amounts": [ { "amount": 824.2, "iso_currency_code": "USD", "unofficial_currency_code": null } ], "transactions": [ { "amount": 824.2, "check_number": null, "date": "2024-08-15", "iso_currency_code": "USD", "name": "SSI TREAS 310 XXSUPP SEC PPD ID: 1234567890", "original_description": "SSI TREAS 310 XXSUPP SEC PPD ID: 1234567890", "transaction_id": "nWLlwMm1qxi8DomvDXP3FaGjXX5bm9TAlyQnk", "unofficial_currency_code": null } ], "unofficial_currency_code": null } ], "income_category": "LONG_TERM_DISABILITY", "income_description": "SSI TREAS 310 XXSUPP SEC PPD ID: 1234567890", "income_source_id": "88bc00d8-2bb1-42d0-a054-db3f20948283", "pay_frequency": "UNKNOWN", "start_date": "2024-08-15", "total_amount": 824.2, "transaction_count": 1 }, { "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5", "end_date": "2024-08-08", "historical_summary": [ { "end_date": "2024-08-21", "iso_currency_code": "USD", "start_date": "2024-08-06", "total_amount": 1525, "total_amounts": [ { "amount": 1525, "iso_currency_code": "USD", "unofficial_currency_code": null } ], "transactions": [ { "amount": 1525, "check_number": null, "date": "2024-08-08", "iso_currency_code": "USD", "name": "AIRBNB PAYMENTS PPD ID: 1234567890", "original_description": "AIRBNB PAYMENTS PPD ID: 1234567890", "transaction_id": "Wr6jzLwg1qs6ag9Xa8BrCpBAPPxnEXF6ZmjDR", "unofficial_currency_code": null } ], "unofficial_currency_code": null } ], "income_category": "RENTAL", "income_description": "AIRBNB PAYMENTS PPD ID: 1234567890", "income_source_id": "063689af-7299-4327-b71f-9d8849a40c0e", "pay_frequency": "UNKNOWN", "start_date": "2024-08-08", "total_amount": 1525, "transaction_count": 1 }, { "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5", "end_date": "2024-08-12", "historical_summary": [ { "end_date": "2024-08-21", "iso_currency_code": "USD", "start_date": "2024-08-06", "total_amount": 500, "total_amounts": [ { "amount": 500, "iso_currency_code": "USD", "unofficial_currency_code": null } ], "transactions": [ { "amount": 500, "check_number": null, "date": "2024-08-12", "iso_currency_code": "USD", "name": "TWC-BENEFITS/UI BENEFIT", "original_description": "TWC-BENEFITS/UI BENEFIT", "transaction_id": "Aj7Apx5bDyIA3VRl35yqC18wXXorBgI9rX5dp", "unofficial_currency_code": null } ], "unofficial_currency_code": null } ], "income_category": "UNEMPLOYMENT", "income_description": "TWC-BENEFITS/UI BENEFIT", "income_source_id": "ce160170-49d0-4811-b58e-cb4878d05f83", "pay_frequency": "UNKNOWN", "start_date": "2024-08-12", "total_amount": 500, "transaction_count": 1 }, { "account_id": "G1L9oybBrKSMPmBdPzXoFN8oo16rqqC6PwkA5", "end_date": "2024-08-21", "historical_summary": [ { "end_date": "2024-08-21", "iso_currency_code": "USD", "start_date": "2024-08-06", "total_amount": 240.24, "total_amounts": [ { "amount": 240.24, "iso_currency_code": "USD", "unofficial_currency_code": null } ], "transactions": [ { "amount": 120.12, "check_number": null, "date": "2024-08-07", "iso_currency_code": "USD", "name": "TEXAS OAG CHILD SUPPORT", "original_description": "TEXAS OAG CHILD SUPPORT", "transaction_id": "EZMmvwREqlSGmlRam7bzFKyBll3kJjU4xKm1w", "unofficial_currency_code": null }, { "amount": 120.12, "check_number": null, "date": "2024-08-21", "iso_currency_code": "USD", "name": "TEXAS OAG CHILD SUPPORT", "original_description": "TEXAS OAG CHILD SUPPORT", "transaction_id": "b7dkg6eQbPFQeRvVeZlxcqxZooa7nWSmb47dj", "unofficial_currency_code": null } ], "unofficial_currency_code": null } ], "income_category": "CHILD_SUPPORT", "income_description": "TEXAS OAG CHILD SUPPORT", "income_source_id": "c8e1576e-9de4-47b4-ad55-3f7b068cc863", "pay_frequency": "UNKNOWN", "start_date": "2024-08-07", "total_amount": 240.24, "transaction_count": 2 } ], "institution_id": "ins_20", "institution_name": "Citizens Bank", "item_id": "L8EKo4GydxSKmJQGmXyPuDkeNn4rg9fP3MKLv", "last_updated_time": "2024-08-21T18:10:47.367335Z" } ] } ], "request_id": "MLM1fFu4fbVg7KR" } ``` \=\*=\*=\*= #### /credit/bank\_income/pdf/get  #### Retrieve information from the bank accounts used for income verification in PDF format  [/credit/bank\_income/pdf/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomepdfget) returns the most recent bank income report for a specified user in PDF format. A single report corresponds to all institutions linked in a single Link session. To include multiple institutions in a single report, use [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```node const request: CreditBankIncomePDFGetRequest = { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', }; try { const response = await client.creditBankIncomePdfGet(request, { responseType: 'arraybuffer', }); const pdf = response.buffer.toString('base64'); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/credit/bank_income/pdf/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" }' \ -o 'bank_income.pdf' ``` ```ruby request = Plaid::CreditBankIncomePDFGetRequest.new({ user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' }) response = client.credit_bank_income_pdf_get(request) ``` ```java CreditBankIncomePDFGetRequest request = new CreditBankIncomePDFGetRequest() .userToken("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"); Response response = client() .creditBankIncomePdfGet(request) .execute(); byte[] pdf = response.body().bytes(); ``` ```python request = CreditBankIncomePDFGetRequest(user_token='user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d') pdf = client.credit_bank_income_pdf_get(request) ``` ```go request := plaid.NewCreditBankIncomePDFGetRequest( "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", ) response, _, err := client.PlaidApi.CreditBankIncomePdfGet(ctx).CreditBankIncomePDFGetRequest(*request).Execute() ``` ##### Response  This endpoint returns binary PDF data. [View a sample Bank Income PDF.](https://plaid.com/documents/sample-bank-income.pdf) \=\*=\*=\*= #### /credit/bank\_statements/uploads/get  #### Retrieve data for a user's uploaded bank statements  [/credit/bank\_statements/uploads/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_statementsuploadsget) returns parsed data from bank statements uploaded by users as part of the Document Income flow. If your account is not enabled for Document Parsing, contact your account manager to request access. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . object An optional object for `/credit/bank_statements/uploads/get` request options. \[string\] An array of `item_id`s whose bank statements information is returned. Each `item_id` should uniquely identify a bank statements uploaded item. If this field is not provided, all `item_id`s associated with the `user_token` will returned in the response. ```node const request: CreditBankStatementsUploadsGetRequest = { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', }; try { const response = await client.creditBankStatementsUploadsGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/credit/bank_statements/uploads/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_token": "${USER_TOKEN}", }' ``` ```ruby request = Plaid::CreditBankStatementsUploadsGetRequest.new( { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', } ) response = client.credit_bank_statements_uploads_get(request) ``` ```java CreditBankStatementsUploadsGetRequest request = new CreditBankStatementsUploadsGetRequest() .userToken("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"); Response response = client .creditBankStatementsUploadsGet(request) .execute(); ``` ```python request = CreditBankStatementsUploadsGetRequest( user_token='user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' ) response = client.credit_bank_statements_uploads_get(request) ``` ```go request := plaid.NewCreditBankStatementsUploadsGetRequest( "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", ) response, _, err := client.PlaidApi.CreditBankStatementsUploadsGet(ctx).CreditBankStatementsUploadsGetRequest(*request).Execute() ``` #### Response fields  \[object\] Array of bank statement upload items. string The `item_id` of the Item associated with this webhook, warning, or error \[object\] \[object\] An array of transactions appearing on the bank statement. nullable, number The value of the transaction. A negative amount indicates that money moved into the account (such as a paycheck being deposited). nullable, string The date of when the transaction was made, in ISO 8601 format (YYYY-MM-DD). Format: `date` nullable, string The raw description of the transaction as it appears on the bank statement. nullable, string The unique id of the bank account that this transaction occurs in object Object representing metadata pertaining to the document. string The name of the document. nullable, string The type of document. `PAYSTUB`: A paystub. `BANK_STATEMENT`: A bank statement. `US_TAX_W2`: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee. `US_MILITARY_ERAS`: An electronic Retirement Account Statement (eRAS) issued by the US military. `US_MILITARY_LES`: A Leave and Earnings Statement (LES) issued by the US military. `US_MILITARY_CLES`: A Civilian Leave and Earnings Statement (CLES) issued by the US military. `GIG`: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type. `PLAID_GENERATED_PAYSTUB_PDF`: Used to indicate that the PDF for the paystub was generated by Plaid. `NONE`: Used to indicate that there is no underlying document for the data. `UNKNOWN`: Document type could not be determined. Possible values: `UNKNOWN`, `PAYSTUB`, `BANK_STATEMENT`, `US_TAX_W2`, `US_MILITARY_ERAS`, `US_MILITARY_LES`, `US_MILITARY_CLES`, `GIG`, `PLAID_GENERATED_PAYSTUB_PDF`, `NONE` nullable, string Signed URL to retrieve the document(s). The payload will be a .zip file containing the document(s). For Payroll Income, the file type of the documents will always be PDF, and the documents may not be available, in which case the field will be `null`. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. [Example generated pay stub](https://plaid.com/documents/plaid-generated-mock-paystub.pdf) . For Document Income, this field will not be `null`, and the file type of the underlying document(s) will be the original file type uploaded by the user. For more details on available file types, see the [Document Income](https://plaid.com/docs/income/payroll-income/index.html.md) documentation. This download URL can only be used once and expires after two minutes. To generate a new download URL, call `/credit/payroll_income/get` again. nullable, string The processing status of the document. `PROCESSING_COMPLETE`: The document was successfully processed. `DOCUMENT_ERROR`: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted. `UNKNOWN` or `null`: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager. Possible values: `UNKNOWN`, `PROCESSING_COMPLETE`, `DOCUMENT_ERROR`, `null` nullable, integer The number of pages of the uploaded document (if available). nullable, string The reason why a failure occurred during document processing (if available). nullable, string An identifier of the document referenced by the document metadata. \[object\] An array of bank accounts associated with the uploaded bank statement. nullable, string The name of the bank account nullable, string The name of the bank institution. nullable, string The type of the bank account. nullable, string The bank account number. object An object containing data about the owner of the bank account for the uploaded bank statement. nullable, string The name of the account owner object Address on the uploaded bank statement nullable, string The full city name. nullable, string The ISO 3166-1 alpha-2 country code. nullable, string The postal code of the address. nullable, string The region or state. Example: `"NC"` nullable, string The full street address. \[object\] An array of period objects, containing more data on the overall period of the statement. nullable, string The start date of the statement period in ISO 8601 format (YYYY-MM-DD). Format: `date` nullable, string The end date of the statement period in ISO 8601 format (YYYY-MM-DD). Format: `date` nullable, number The starting balance of the bank account for the period. nullable, number The ending balance of the bank account for the period. nullable, string The unique id of the bank account nullable, object Details about the status of the payroll item. nullable, string Denotes the processing status for the verification. `UNKNOWN`: The processing status could not be determined. `PROCESSING_COMPLETE`: The processing has completed and the user has approved for sharing. The data is available to be retrieved. `PROCESSING`: The verification is still processing. The data is not available yet. `FAILED`: The processing failed to complete successfully. `APPROVAL_STATUS_PENDING`: The processing has completed but the user has not yet approved the sharing of the data. Possible values: `UNKNOWN`, `PROCESSING_COMPLETE`, `PROCESSING`, `FAILED`, `APPROVAL_STATUS_PENDING` nullable, string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "items": [ { "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "bank_statements": [ { "transactions": [ { "amount": -1000, "date": "2023-01-01", "original_description": "PAYCHECK", "account_id": "c6778d3f-e44c-4348-874e-71507c1ac12d" } ], "document_metadata": { "document_type": "BANK_STATEMENT", "name": "statement_01.pdf", "status": "PROCESSING_COMPLETE", "download_url": null, "page_count": 2 }, "document_id": "2jkflanbd", "bank_accounts": [ { "name": "CHASE CHECKING", "bank_name": "CHASE", "account_type": "CHECKING", "account_number": "000009752", "account_id": "c6778d3f-e44c-4348-874e-71507c1ac12d", "owner": { "name": "JANE DOE", "address": { "postal_code": "94133", "country": "US", "region": "CA", "city": "SAN FRANCISCO", "street": "2140 TAYLOR ST" } }, "periods": [ { "start_date": "2023-01-01", "end_date": "2023-02-01", "starting_balance": 2500, "ending_balance": 3500 } ] } ] } ], "status": { "processing_status": "PROCESSING_COMPLETE" }, "updated_at": "2023-02-01T21:14:54Z" } ], "request_id": "LhQf0THi8SH1yJm" } ``` \=\*=\*=\*= #### /credit/payroll\_income/get  #### Retrieve a user's payroll information  This endpoint gets payroll income information for a specific user, either as a result of the user connecting to their payroll provider or uploading a pay related document. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . object An optional object for `/credit/payroll_income/get` request options. \[string\] An array of `item_id`s whose payroll information is returned. Each `item_id` should uniquely identify a payroll income item. If this field is not provided, all `item_id`s associated with the `user_token` will returned in the response. ```node const request: CreditPayrollIncomeGetRequest = { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', }; try { const response = await client.creditPayrollIncomeGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/credit/payroll_income/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" }' ``` ```ruby request = Plaid::CreditPayrollIncomeGetRequest.new( { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' } ) response = client.credit_payroll_income_get(request) ``` ```java CreditPayrollIncomeGetRequest request = new CreditPayrollIncomeGetRequest() .userToken("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"); Response response = client .creditPayrollIncomeGet(request) .execute(); ``` ```python request = CreditPayrollIncomeGetRequest( user_token='user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' ) response = client.credit_payroll_income_get(request) ``` ```go request := plaid.NewCreditPayrollIncomeGetRequest( "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", ) response, _, err := client.PlaidApi.CreditPayrollIncomeGet(ctx).CreditPayrollIncomeGetRequest(*request).Execute() ``` #### Response fields  \[object\] Array of payroll items. string The `item_id` of the Item associated with this webhook, warning, or error string The unique identifier of the institution associated with the Item. string The name of the institution associated with the Item. \[object\] nullable, string ID of the payroll provider account. object An object representing the rate at which an individual is paid. nullable, string The rate at which an employee is paid. Possible values: `ANNUAL`, `HOURLY`, `CONTRACT`, `WEEKLY`, `BIWEEKLY`, `MONTHLY`, `SEMI_MONTHLY`, `DAILY`, `COMMISSION`, `OTHER`, `null` nullable, number The amount at which an employee is paid. Format: `double` nullable, string The frequency at which an individual is paid. Possible values: `DAILY`, `WEEKLY`, `BIWEEKLY`, `SEMI_MONTHLY`, `MONTHLY`, `CONTRACT`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `OTHER`, `null` \[object\] nullable, string ID of the payroll provider account. \[object\] Array of pay stubs for the user. object An object with the deduction information found on a pay stub. \[object\] nullable, number Raw amount of the deduction Format: `double` nullable, string Description of the deduction line item nullable, string The ISO-4217 currency code of the line item. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the line item. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, number The year-to-date amount of the deduction Format: `double` object An object representing the total deductions for the pay period nullable, number Raw amount of the deduction Format: `double` nullable, string The ISO-4217 currency code of the line item. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the line item. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, number The year-to-date total amount of the deductions Format: `double` nullable, string An identifier of the document referenced by the document metadata. object Object representing metadata pertaining to the document. string The name of the document. nullable, string The type of document. `PAYSTUB`: A paystub. `BANK_STATEMENT`: A bank statement. `US_TAX_W2`: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee. `US_MILITARY_ERAS`: An electronic Retirement Account Statement (eRAS) issued by the US military. `US_MILITARY_LES`: A Leave and Earnings Statement (LES) issued by the US military. `US_MILITARY_CLES`: A Civilian Leave and Earnings Statement (CLES) issued by the US military. `GIG`: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type. `PLAID_GENERATED_PAYSTUB_PDF`: Used to indicate that the PDF for the paystub was generated by Plaid. `NONE`: Used to indicate that there is no underlying document for the data. `UNKNOWN`: Document type could not be determined. Possible values: `UNKNOWN`, `PAYSTUB`, `BANK_STATEMENT`, `US_TAX_W2`, `US_MILITARY_ERAS`, `US_MILITARY_LES`, `US_MILITARY_CLES`, `GIG`, `PLAID_GENERATED_PAYSTUB_PDF`, `NONE` nullable, string Signed URL to retrieve the document(s). The payload will be a .zip file containing the document(s). For Payroll Income, the file type of the documents will always be PDF, and the documents may not be available, in which case the field will be `null`. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. [Example generated pay stub](https://plaid.com/documents/plaid-generated-mock-paystub.pdf) . For Document Income, this field will not be `null`, and the file type of the underlying document(s) will be the original file type uploaded by the user. For more details on available file types, see the [Document Income](https://plaid.com/docs/income/payroll-income/index.html.md) documentation. This download URL can only be used once and expires after two minutes. To generate a new download URL, call `/credit/payroll_income/get` again. nullable, string The processing status of the document. `PROCESSING_COMPLETE`: The document was successfully processed. `DOCUMENT_ERROR`: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted. `UNKNOWN` or `null`: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager. Possible values: `UNKNOWN`, `PROCESSING_COMPLETE`, `DOCUMENT_ERROR`, `null` nullable, integer The number of pages of the uploaded document (if available). nullable, string The reason why a failure occurred during document processing (if available). object An object representing both a breakdown of earnings on a pay stub and the total earnings. \[object\] nullable, string Commonly used term to describe the earning line item. Possible values: `BONUS`, `COMMISSION`, `OVERTIME`, `PAID_TIME_OFF`, `REGULAR_PAY`, `VACATION`, `BASIC_ALLOWANCE_HOUSING`, `BASIC_ALLOWANCE_SUBSISTENCE`, `OTHER`, `ALLOWANCE`, `BEREAVEMENT`, `HOLIDAY_PAY`, `JURY_DUTY`, `LEAVE`, `LONG_TERM_DISABILITY_PAY`, `MILITARY_PAY`, `PER_DIEM`, `REFERRAL_BONUS`, `REIMBURSEMENTS`, `RETENTION_BONUS`, `RETROACTIVE_PAY`, `SEVERANCE_PAY`, `SHIFT_DIFFERENTIAL`, `SHORT_TERM_DISABILITY_PAY`, `SICK_PAY`, `SIGNING_BONUS`, `TIPS_INCOME`, `RETIREMENT`, `GIG_ECONOMY`, `STOCK_COMPENSATION`, `null` nullable, number Raw amount of the earning line item. Format: `double` nullable, string Description of the earning line item. nullable, number Number of hours applicable for this earning. nullable, string The ISO-4217 currency code of the line item. Always `null` if `unofficial_currency_code` is non-null. nullable, number Hourly rate applicable for this earning. Format: `double` nullable, string The unofficial currency code associated with the line item. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, number The year-to-date amount of the deduction. Format: `double` object An object representing both the current pay period and year to date amount for an earning category. nullable, number Total amount of the earnings for this pay period. Format: `double` nullable, number Total number of hours worked for this pay period. nullable, string The ISO-4217 currency code of the line item. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the security. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, number The total year-to-date amount of the earnings. Format: `double` object Data about the employee. object Address on the pay stub. nullable, string The full city name. nullable, string The ISO 3166-1 alpha-2 country code. nullable, string The postal code of the address. nullable, string The region or state. Example: `"NC"` nullable, string The full street address. nullable, string The name of the employee. nullable, string Marital status of the employee - either `SINGLE` or `MARRIED` or `NOT LISTED`. Possible values: `SINGLE`, `MARRIED`, `NOT LISTED`, `null` object Taxpayer ID of the individual receiving the paystub. nullable, string Type of ID, e.g. 'SSN'. nullable, string ID mask; i.e. last 4 digits of the taxpayer ID. object Information about the employer on the pay stub. object Address on the pay stub. nullable, string The full city name. nullable, string The ISO 3166-1 alpha-2 country code. nullable, string The postal code of the address. nullable, string The region or state. Example: `"NC"` nullable, string The full street address. nullable, string The name of the employer on the pay stub. object An object representing information about the net pay amount on the pay stub. nullable, number Raw amount of the net pay for the pay period. Format: `double` nullable, string Description of the net pay. nullable, string The ISO-4217 currency code of the net pay. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the net pay. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, number The year-to-date amount of the net pay. Format: `double` object Details about the pay period. nullable, number The amount of the paycheck. Format: `double` \[object\] nullable, string Name of the account for the given distribution. nullable, string The name of the bank that the payment is being deposited to. nullable, number The amount distributed to this account. Format: `double` nullable, string The ISO-4217 currency code of the net pay. Always `null` if `unofficial_currency_code` is non-null. nullable, string The last 2-4 alphanumeric characters of an account's official account number. nullable, string Type of the account that the paystub was sent to (e.g. 'checking'). nullable, string The unofficial currency code associated with the net pay. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The date on which the pay period ended, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). Format: `date` nullable, number Total earnings before tax/deductions. Format: `double` nullable, string The ISO-4217 currency code of the net pay. Always `null` if `unofficial_currency_code` is non-null. nullable, string The date on which the pay stub was issued, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). Format: `date` nullable, string The frequency at which an individual is paid. Possible values: `UNKNOWN`, `WEEKLY`, `BIWEEKLY`, `SEMI_MONTHLY`, `MONTHLY`, `null` string The explicit pay basis on the paystub (if present). Possible values: `SALARY`, `HOURLY`, `COMMISSION` nullable, string The date on which the pay period started, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). Format: `date` nullable, string The unofficial currency code associated with the net pay. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. \[object\] Array of tax form W-2s. object Object representing metadata pertaining to the document. string The name of the document. nullable, string The type of document. `PAYSTUB`: A paystub. `BANK_STATEMENT`: A bank statement. `US_TAX_W2`: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee. `US_MILITARY_ERAS`: An electronic Retirement Account Statement (eRAS) issued by the US military. `US_MILITARY_LES`: A Leave and Earnings Statement (LES) issued by the US military. `US_MILITARY_CLES`: A Civilian Leave and Earnings Statement (CLES) issued by the US military. `GIG`: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type. `PLAID_GENERATED_PAYSTUB_PDF`: Used to indicate that the PDF for the paystub was generated by Plaid. `NONE`: Used to indicate that there is no underlying document for the data. `UNKNOWN`: Document type could not be determined. Possible values: `UNKNOWN`, `PAYSTUB`, `BANK_STATEMENT`, `US_TAX_W2`, `US_MILITARY_ERAS`, `US_MILITARY_LES`, `US_MILITARY_CLES`, `GIG`, `PLAID_GENERATED_PAYSTUB_PDF`, `NONE` nullable, string Signed URL to retrieve the document(s). The payload will be a .zip file containing the document(s). For Payroll Income, the file type of the documents will always be PDF, and the documents may not be available, in which case the field will be `null`. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. [Example generated pay stub](https://plaid.com/documents/plaid-generated-mock-paystub.pdf) . For Document Income, this field will not be `null`, and the file type of the underlying document(s) will be the original file type uploaded by the user. For more details on available file types, see the [Document Income](https://plaid.com/docs/income/payroll-income/index.html.md) documentation. This download URL can only be used once and expires after two minutes. To generate a new download URL, call `/credit/payroll_income/get` again. nullable, string The processing status of the document. `PROCESSING_COMPLETE`: The document was successfully processed. `DOCUMENT_ERROR`: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted. `UNKNOWN` or `null`: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager. Possible values: `UNKNOWN`, `PROCESSING_COMPLETE`, `DOCUMENT_ERROR`, `null` nullable, integer The number of pages of the uploaded document (if available). nullable, string The reason why a failure occurred during document processing (if available). string An identifier of the document referenced by the document metadata. object Information about the employer on the pay stub. object Address on the pay stub. nullable, string The full city name. nullable, string The ISO 3166-1 alpha-2 country code. nullable, string The postal code of the address. nullable, string The region or state. Example: `"NC"` nullable, string The full street address. nullable, string The name of the employer on the pay stub. object Data about the employee. object Address on the pay stub. nullable, string The full city name. nullable, string The ISO 3166-1 alpha-2 country code. nullable, string The postal code of the address. nullable, string The region or state. Example: `"NC"` nullable, string The full street address. nullable, string The name of the employee. nullable, string Marital status of the employee - either `SINGLE` or `MARRIED` or `NOT LISTED`. Possible values: `SINGLE`, `MARRIED`, `NOT LISTED`, `null` object Taxpayer ID of the individual receiving the paystub. nullable, string Type of ID, e.g. 'SSN'. nullable, string ID mask; i.e. last 4 digits of the taxpayer ID. nullable, string The tax year of the W2 document. nullable, string An employee identification number or EIN. nullable, string Wages from tips and other compensation. nullable, string Federal income tax withheld for the tax year. nullable, string Wages from social security. nullable, string Social security tax withheld for the tax year. nullable, string Wages and tips from medicare. nullable, string Medicare tax withheld for the tax year. nullable, string Tips from social security. nullable, string Allocated tips. nullable, string Contents from box 9 on the W2. nullable, string Dependent care benefits. nullable, string Nonqualified plans. \[object\] nullable, string W2 Box 12 code. nullable, string W2 Box 12 amount. nullable, string Statutory employee. nullable, string Retirement plan. nullable, string Third party sick pay. nullable, string Other. \[object\] nullable, string State associated with the wage. nullable, string State identification number of the employer. nullable, string Wages and tips from the specified state. nullable, string Income tax from the specified state. nullable, string Wages and tips from the locality. nullable, string Income tax from the locality. nullable, string Name of the locality. \[object\] Array of tax form 1099s. nullable, string An identifier of the document referenced by the document metadata. object Object representing metadata pertaining to the document. string The name of the document. nullable, string The type of document. `PAYSTUB`: A paystub. `BANK_STATEMENT`: A bank statement. `US_TAX_W2`: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee. `US_MILITARY_ERAS`: An electronic Retirement Account Statement (eRAS) issued by the US military. `US_MILITARY_LES`: A Leave and Earnings Statement (LES) issued by the US military. `US_MILITARY_CLES`: A Civilian Leave and Earnings Statement (CLES) issued by the US military. `GIG`: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type. `PLAID_GENERATED_PAYSTUB_PDF`: Used to indicate that the PDF for the paystub was generated by Plaid. `NONE`: Used to indicate that there is no underlying document for the data. `UNKNOWN`: Document type could not be determined. Possible values: `UNKNOWN`, `PAYSTUB`, `BANK_STATEMENT`, `US_TAX_W2`, `US_MILITARY_ERAS`, `US_MILITARY_LES`, `US_MILITARY_CLES`, `GIG`, `PLAID_GENERATED_PAYSTUB_PDF`, `NONE` nullable, string Signed URL to retrieve the document(s). The payload will be a .zip file containing the document(s). For Payroll Income, the file type of the documents will always be PDF, and the documents may not be available, in which case the field will be `null`. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. [Example generated pay stub](https://plaid.com/documents/plaid-generated-mock-paystub.pdf) . For Document Income, this field will not be `null`, and the file type of the underlying document(s) will be the original file type uploaded by the user. For more details on available file types, see the [Document Income](https://plaid.com/docs/income/payroll-income/index.html.md) documentation. This download URL can only be used once and expires after two minutes. To generate a new download URL, call `/credit/payroll_income/get` again. nullable, string The processing status of the document. `PROCESSING_COMPLETE`: The document was successfully processed. `DOCUMENT_ERROR`: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted. `UNKNOWN` or `null`: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager. Possible values: `UNKNOWN`, `PROCESSING_COMPLETE`, `DOCUMENT_ERROR`, `null` nullable, integer The number of pages of the uploaded document (if available). nullable, string The reason why a failure occurred during document processing (if available). string Form 1099 Type Possible values: `FORM_1099_TYPE_UNKNOWN`, `FORM_1099_TYPE_MISC`, `FORM_1099_TYPE_K` object An object representing a recipient used in both 1099-K and 1099-MISC tax documents. object Address on the pay stub. nullable, string The full city name. nullable, string The ISO 3166-1 alpha-2 country code. nullable, string The postal code of the address. nullable, string The region or state. Example: `"NC"` nullable, string The full street address. nullable, string Name of recipient. nullable, string Tax identification number of recipient. nullable, string Account number number of recipient. nullable, string Checked if FACTA is a filing requirement. Possible values: `CHECKED`, `NOT CHECKED` nullable, string Checked if 2nd TIN exists. Possible values: `CHECKED`, `NOT CHECKED` object An object representing a payer used by 1099-MISC tax documents. object Address on the pay stub. nullable, string The full city name. nullable, string The ISO 3166-1 alpha-2 country code. nullable, string The postal code of the address. nullable, string The region or state. Example: `"NC"` nullable, string The full street address. nullable, string Name of payer. nullable, string Tax identification number of payer. nullable, string Telephone number of payer. object An object representing a filer used by 1099-K tax documents. object Address on the pay stub. nullable, string The full city name. nullable, string The ISO 3166-1 alpha-2 country code. nullable, string The postal code of the address. nullable, string The region or state. Example: `"NC"` nullable, string The full street address. nullable, string Name of filer. nullable, string Tax identification number of filer. nullable, string One of the following values will be provided: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party Possible values: `Payment Settlement Entity (PSE)`, `Electronic Payment Facilitator (EPF)`, `Other Third Party` nullable, string Tax year of the tax form. nullable, number Amount in rent by payer. Format: `double` nullable, number Amount in royalties by payer. Format: `double` nullable, number Amount in other income by payer. Format: `double` nullable, number Amount of federal income tax withheld from payer. Format: `double` nullable, number Amount of fishing boat proceeds from payer. Format: `double` nullable, number Amount of medical and healthcare payments from payer. Format: `double` nullable, number Amount of nonemployee compensation from payer. Format: `double` nullable, number Amount of substitute payments made by payer. Format: `double` nullable, string Whether or not payer made direct sales over $5000 of consumer products. nullable, number Amount of crop insurance proceeds. Format: `double` nullable, number Amount of golden parachute payments made by payer. Format: `double` nullable, number Amount of gross proceeds paid to an attorney by payer. Format: `double` nullable, number Amount of 409A deferrals earned by payer. Format: `double` nullable, number Amount of 409A income earned by payer. Format: `double` nullable, number Amount of state tax withheld of payer for primary state. Format: `double` nullable, number Amount of state tax withheld of payer for secondary state. Format: `double` nullable, string Primary state ID. nullable, string Secondary state ID. nullable, number State income reported for primary state. Format: `double` nullable, number State income reported for secondary state. Format: `double` nullable, string One of the values will be provided Payment card Third party network Possible values: `Payment card`, `Third party network` nullable, string Name of the PSE (Payment Settlement Entity). nullable, string Formatted (XXX) XXX-XXXX. Phone number of the PSE (Payment Settlement Entity). nullable, number Gross amount reported. Format: `double` nullable, number Amount in card not present transactions. Format: `double` nullable, string Merchant category of filer. nullable, string Number of payment transactions made. nullable, number Amount reported for January. Format: `double` nullable, number Amount reported for February. Format: `double` nullable, number Amount reported for March. Format: `double` nullable, number Amount reported for April. Format: `double` nullable, number Amount reported for May. Format: `double` nullable, number Amount reported for June. Format: `double` nullable, number Amount reported for July. Format: `double` nullable, number Amount reported for August. Format: `double` nullable, number Amount reported for September. Format: `double` nullable, number Amount reported for October. Format: `double` nullable, number Amount reported for November. Format: `double` nullable, number Amount reported for December. Format: `double` nullable, string Primary state of business. nullable, string Secondary state of business. nullable, string Primary state ID. nullable, string Secondary state ID. nullable, number State income tax reported for primary state. Format: `double` nullable, number State income tax reported for secondary state. Format: `double` nullable, object Details about the status of the payroll item. nullable, string Denotes the processing status for the verification. `UNKNOWN`: The processing status could not be determined. `PROCESSING_COMPLETE`: The processing has completed and the user has approved for sharing. The data is available to be retrieved. `PROCESSING`: The verification is still processing. The data is not available yet. `FAILED`: The processing failed to complete successfully. `APPROVAL_STATUS_PENDING`: The processing has completed but the user has not yet approved the sharing of the data. Possible values: `UNKNOWN`, `PROCESSING_COMPLETE`, `PROCESSING`, `FAILED`, `APPROVAL_STATUS_PENDING` nullable, string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated. Format: `date-time` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "items": [ { "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "institution_id": "ins_92", "institution_name": "ADP", "accounts": [ { "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9", "rate_of_pay": { "pay_amount": 100000, "pay_rate": "ANNUAL" }, "pay_frequency": "BIWEEKLY" } ], "payroll_income": [ { "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9", "pay_stubs": [ { "deductions": { "breakdown": [ { "current_amount": 123.45, "description": "taxes", "iso_currency_code": "USD", "unofficial_currency_code": null, "ytd_amount": 246.9 } ], "total": { "current_amount": 123.45, "iso_currency_code": "USD", "unofficial_currency_code": null, "ytd_amount": 246.9 } }, "document_metadata": { "document_type": "PAYSTUB", "name": "paystub.pdf", "status": "PROCESSING_COMPLETE", "download_url": null }, "document_id": "2jkflanbd", "earnings": { "breakdown": [ { "canonical_description": "REGULAR_PAY", "current_amount": 200.22, "description": "salary earned", "hours": 80, "iso_currency_code": "USD", "rate": null, "unofficial_currency_code": null, "ytd_amount": 400.44 }, { "canonical_description": "BONUS", "current_amount": 100, "description": "bonus earned", "hours": null, "iso_currency_code": "USD", "rate": null, "unofficial_currency_code": null, "ytd_amount": 100 } ], "total": { "current_amount": 300.22, "hours": 160, "iso_currency_code": "USD", "unofficial_currency_code": null, "ytd_amount": 500.44 } }, "employee": { "address": { "city": "SAN FRANCISCO", "country": "US", "postal_code": "94133", "region": "CA", "street": "2140 TAYLOR ST" }, "name": "ANNA CHARLESTON", "marital_status": "SINGLE", "taxpayer_id": { "id_type": "SSN", "id_mask": "3333" } }, "employer": { "name": "PLAID INC", "address": { "city": "SAN FRANCISCO", "country": "US", "postal_code": "94111", "region": "CA", "street": "1098 HARRISON ST" } }, "net_pay": { "current_amount": 123.34, "description": "TOTAL NET PAY", "iso_currency_code": "USD", "unofficial_currency_code": null, "ytd_amount": 253.54 }, "pay_period_details": { "distribution_breakdown": [ { "account_name": "Big time checking", "bank_name": "bank of plaid", "current_amount": 176.77, "iso_currency_code": "USD", "mask": "1223", "type": "checking", "unofficial_currency_code": null } ], "end_date": "2020-12-15", "gross_earnings": 4500, "iso_currency_code": "USD", "pay_amount": 1490.21, "pay_date": "2020-12-15", "pay_frequency": "BIWEEKLY", "start_date": "2020-12-01", "unofficial_currency_code": null } } ], "w2s": [ { "allocated_tips": "1000", "box_12": [ { "amount": "200", "code": "AA" } ], "box_9": "box9", "dependent_care_benefits": "1000", "document_metadata": { "document_type": "US_TAX_W2", "download_url": null, "name": "w_2.pdf", "status": "PROCESSING_COMPLETE" }, "document_id": "1pkflebk4", "employee": { "address": { "city": "San Francisco", "country": "US", "postal_code": "94103", "region": "CA", "street": "1234 Grand St" }, "name": "Josie Georgia Harrison", "marital_status": "SINGLE", "taxpayer_id": { "id_type": "SSN", "id_mask": "1234" } }, "employer": { "address": { "city": "New York", "country": "US", "postal_code": "10010", "region": "NY", "street": "456 Main St" }, "name": "Acme Inc" }, "employer_id_number": "12-1234567", "federal_income_tax_withheld": "1000", "medicare_tax_withheld": "1000", "medicare_wages_and_tips": "1000", "nonqualified_plans": "1000", "other": "other", "retirement_plan": "CHECKED", "social_security_tax_withheld": "1000", "social_security_tips": "1000", "social_security_wages": "1000", "state_and_local_wages": [ { "employer_state_id_number": "11111111111AAA", "local_income_tax": "200", "local_wages_and_tips": "200", "locality_name": "local", "state": "UT", "state_income_tax": "200", "state_wages_tips": "200" } ], "statutory_employee": "CHECKED", "tax_year": "2020", "third_party_sick_pay": "CHECKED", "wages_tips_other_comp": "1000" } ], "form1099s": [ { "april_amount": null, "august_amount": null, "card_not_present_transaction": null, "crop_insurance_proceeds": 1000, "december_amount": null, "document_id": "mvMZ59Z2a5", "document_metadata": { "document_type": "US_TAX_1099_MISC", "download_url": null, "name": "form_1099_misc.pdf", "status": "PROCESSING_COMPLETE" }, "excess_golden_parachute_payments": 1000, "february_amount": null, "federal_income_tax_withheld": 1000, "filer": { "address": { "city": null, "country": null, "postal_code": null, "region": null, "street": null }, "name": null, "tin": null, "type": null }, "fishing_boat_proceeds": 1000, "form_1099_type": "FORM_1099_TYPE_MISC", "gross_amount": 1000, "gross_proceeds_paid_to_an_attorney": 1000, "january_amount": null, "july_amount": null, "june_amount": null, "march_amount": null, "may_amount": null, "medical_and_healthcare_payments": 1000, "merchant_category_code": null, "nonemployee_compensation": 1000, "november_amount": null, "number_of_payment_transactions": null, "october_amount": null, "other_income": 1000, "payer": { "address": { "city": "SAN FRANCISCO", "country": "US", "postal_code": "94111", "region": "CA", "street": "1098 HARRISON ST" }, "name": "PLAID INC", "telephone_number": "(123)456-7890", "tin": "12-3456789" }, "payer_made_direct_sales_of_500_or_more_of_consumer_products_to_buyer": null, "payer_state_number": "CA 12345", "payer_state_number_lower": null, "primary_state": null, "primary_state_id": "CA 12345", "primary_state_income_tax": 1000, "pse_name": null, "pse_telephone_number": null, "recipient": { "account_number": "45678", "address": { "city": "SAN FRANCISCO", "country": "US", "postal_code": "94133", "region": "CA", "street": "2140 TAYLOR ST" }, "facta_filing_requirement": "CHECKED", "name": "Josie Georgia Harrison", "second_tin_exists": "NOT CHECKED", "tin": "12-3456789" }, "rents": 1000, "royalties": 1000, "secondary_state": null, "secondary_state_id": null, "secondary_state_income_tax": null, "section_409a_deferrals": 1000, "section_409a_income": 1000, "september_amount": null, "state_income": 1000, "state_income_lower": null, "state_tax_withheld": 1000, "state_tax_withheld_lower": null, "substitute_payments_in_lieu_of_dividends_or_interest": null, "tax_year": "2022", "transactions_reported": null } ] } ], "status": { "processing_status": "PROCESSING_COMPLETE" }, "updated_at": "2022-08-02T21:14:54Z" } ], "request_id": "2pxQ59buGdsHRef" } ``` \=\*=\*=\*= #### /credit/payroll\_income/risk\_signals/get  #### Retrieve fraud insights for a user's manually uploaded document(s).  [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) can be used as part of the Document Income flow to assess a user-uploaded document for signs of potential fraud or tampering. It returns a risk score for each uploaded document that indicates the likelihood of the document being fraudulent, in addition to details on the individual risk signals contributing to the score. To trigger risk signal generation for an Item, call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with `parsing_config` set to include `risk_signals`, or call [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) . Once risk signal generation has been triggered, [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) can be called at any time after the `INCOME_VERIFICATION_RISK_SIGNALS` webhook has been fired. [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) is offered as an add-on to Document Income and is billed separately. To request access to this endpoint, submit a product access request or contact your Plaid account manager. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash -X POST https://sandbox.plaid.com/credit/payroll_income/risk_signals/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_token": "user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12" }' ``` ```node const request: CreditPayrollIncomeRiskSignalsGetRequest = { user_token: 'user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12', }; try { const response = await client.creditPayrollIncomeRiskSignalsGet(request); } catch (error) { // handle error } ``` ```python request = CreditPayrollIncomeRiskSignalsGetRequest( user_token='user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12', ) response = client.credit_payroll_income_risk_signals_get(request) ``` ```ruby request = Plaid::CreditPayrollIncomeRiskSignalsGetRequest.new( { user_token: 'user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12', } ) response = client.credit_payroll_income_risk_signals_get(request) ``` ```go request := plaid.NewCreditPayrollIncomeRiskSignalsGetRequest( "user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12", ) response, _, err := client.PlaidApi.CreditPayrollIncomeRiskSignalsGet(ctx).CreditPayrollIncomeRiskSignalsGetRequest(*request).Execute() ``` ```java CreditPayrollIncomeRiskSignalsGetRequest request = new CreditPayrollIncomeRiskSignalsGetRequest() .userToken("user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12"); Response response = client .CreditPayrollIncomeRiskSignalsGet(request) .execute(); ``` #### Response fields  \[object\] Array of payroll items. string The `item_id` of the Item associated with this webhook, warning, or error \[object\] Array of payroll income document authenticity data retrieved for each of the user's accounts. nullable, string ID of the payroll provider account. \[object\] Array of document metadata and associated risk signals per document object Object containing metadata for the document nullable, string An identifier of the document referenced by the document metadata. string The name of the document string Status of a document for risk signal analysis Possible values: `PROCESSING`, `PROCESSING_COMPLETE`, `PROCESSING_ERROR`, `PASSWORD_PROTECTED`, `VIRUS_DETECTED` nullable, string Type of a document for risk signal analysis Possible values: `UNKNOWN`, `BANK_STATEMENT`, `BENEFITS_STATEMENT`, `BUSINESS_FILING`, `CHECK`, `DRIVING_LICENSE`, `FINANCIAL_STATEMENT`, `INVOICE`, `PAYSLIP`, `SOCIAL_SECURITY_CARD`, `TAX_FORM`, `UTILITY_BILL` nullable, string The file type for risk signal analysis Possible values: `UNKNOWN`, `IMAGE_PDF`, `SCAN_OCR`, `TRUE_PDF`, `IMAGE`, `MIXED_PAGE_PDF`, `EMPTY_PDF`, `FLATTENED_PDF` \[object\] Array of attributes that indicate whether or not there is fraud risk with a document nullable, string The type of risk found in the risk signal check. Possible values: `FONT`, `MASKING`, `OVERLAID_TEXT`, `EDITED_TEXT`, `TEXT_COMPRESSION`, `ADDRESS_FORMAT_ANOMALY`, `DATE_FORMAT_ANOMALY`, `FONT_ANOMALY`, `NAME_FORMAT_ANOMALY`, `PDF_ALIGNMENT`, `BRUSH_DETECTION`, `METADATA_DATES_OUTSIDE_WINDOW`, `METADATA_DATES_INSIDE_WINDOW`, `METADATA_DATES_MISSING`, `METADATA_DATES_MATCH`, `ADOBE_FONTS`, `ANNOTATION_DATES`, `ANNOTATIONS`, `EDITED_WHILE_SCANNED`, `EXIF_DATA_MODIFIED`, `HIGH_USER_ACCESS`, `MALFORMED_DATE`, `QPDF`, `TEXT_LAYER_TEXT`, `TOUCHUP_TEXT`, `FLATTENED_PDF`, `BLACKLISTS`, `COPYCAT_IMAGE`, `COPYCAT_TEXT`, `REJECTED_CUSTOMER`, `TEMPLATES`, `SOFTWARE_BLACKLIST` nullable, string The field which the risk signal was computed for nullable, boolean A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent nullable, object An object which contains additional metadata about the institution used to compute the verification attribute string The `item_id` of the Item associated with this webhook, warning, or error nullable, string The expected value of the field, as seen on the document nullable, string The derived value obtained in the risk signal calculation process for this field nullable, string A human-readable explanation providing more detail into the particular risk signal nullable, integer The relevant page associated with the risk signal. If the risk signal is not associated with a specific page, the value will be 0. object A summary across all risk signals associated with a document nullable, number A number between 0 and 100, inclusive, where a score closer to 0 indicates a document is likely to be trustworthy and a score closer to 100 indicates a document is likely to be fraudulent. You can automatically reject documents with a high risk score, automatically accept documents with a low risk score, and manually review documents in between. We suggest starting with a threshold of 80 for auto-rejection and 20 for auto-acceptance. As you gather more data points on typical risk scores for your use case, you can tune these parameters to reduce the number of documents undergoing manual review. \[object\] Array of risk signals computed from a set of uploaded documents and the associated documents' metadata \[object\] Array of objects containing attributes that could indicate if a document is fraudulent nullable, string An identifier of the document referenced by the document metadata. string The name of the document string Status of a document for risk signal analysis Possible values: `PROCESSING`, `PROCESSING_COMPLETE`, `PROCESSING_ERROR`, `PASSWORD_PROTECTED`, `VIRUS_DETECTED` nullable, string Type of a document for risk signal analysis Possible values: `UNKNOWN`, `BANK_STATEMENT`, `BENEFITS_STATEMENT`, `BUSINESS_FILING`, `CHECK`, `DRIVING_LICENSE`, `FINANCIAL_STATEMENT`, `INVOICE`, `PAYSLIP`, `SOCIAL_SECURITY_CARD`, `TAX_FORM`, `UTILITY_BILL` nullable, string The file type for risk signal analysis Possible values: `UNKNOWN`, `IMAGE_PDF`, `SCAN_OCR`, `TRUE_PDF`, `IMAGE`, `MIXED_PAGE_PDF`, `EMPTY_PDF`, `FLATTENED_PDF` \[object\] Array of attributes that indicate whether or not there is fraud risk with a set of documents nullable, string The type of risk found in the risk signal check. Possible values: `FONT`, `MASKING`, `OVERLAID_TEXT`, `EDITED_TEXT`, `TEXT_COMPRESSION`, `ADDRESS_FORMAT_ANOMALY`, `DATE_FORMAT_ANOMALY`, `FONT_ANOMALY`, `NAME_FORMAT_ANOMALY`, `PDF_ALIGNMENT`, `BRUSH_DETECTION`, `METADATA_DATES_OUTSIDE_WINDOW`, `METADATA_DATES_INSIDE_WINDOW`, `METADATA_DATES_MISSING`, `METADATA_DATES_MATCH`, `ADOBE_FONTS`, `ANNOTATION_DATES`, `ANNOTATIONS`, `EDITED_WHILE_SCANNED`, `EXIF_DATA_MODIFIED`, `HIGH_USER_ACCESS`, `MALFORMED_DATE`, `QPDF`, `TEXT_LAYER_TEXT`, `TOUCHUP_TEXT`, `FLATTENED_PDF`, `BLACKLISTS`, `COPYCAT_IMAGE`, `COPYCAT_TEXT`, `REJECTED_CUSTOMER`, `TEMPLATES`, `SOFTWARE_BLACKLIST` nullable, string The field which the risk signal was computed for nullable, boolean A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent nullable, object An object which contains additional metadata about the institution used to compute the verification attribute string The `item_id` of the Item associated with this webhook, warning, or error nullable, string The expected value of the field, as seen on the document nullable, string The derived value obtained in the risk signal calculation process for this field nullable, string A human-readable explanation providing more detail into the particular risk signal nullable, integer The relevant page associated with the risk signal. If the risk signal is not associated with a specific page, the value will be 0. nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "items": [ { "item_id": "testItemID", "verification_risk_signals": [ { "account_id": null, "multi_document_risk_signals": [], "single_document_risk_signals": [ { "document_reference": { "document_id": "lRepoQjxlJ1nz", "document_name": "Paystub.pdf", "file_type": "TRUE_PDF" }, "risk_summary": { "risk_score": 70 }, "risk_signals": [ { "actual_value": "0.00", "expected_value": "25.09", "field": null, "signal_description": null, "has_fraud_risk": true, "type": "MASKING", "page_number": 1, "institution_metadata": { "item_id": "testItemID" } }, { "actual_value": null, "expected_value": null, "field": null, "signal_description": "Creation date and modification date do not match", "has_fraud_risk": true, "institution_metadata": null, "type": "METADATA_DATES_OUTSIDE_WINDOW", "page_number": 0 } ] } ] } ] } ], "request_id": "LhQf0THi8SH1yJm" } ``` \=\*=\*=\*= #### /credit/employment/get  #### Retrieve a summary of an individual's employment information  [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) returns a list of items with employment information from a user's payroll provider that was verified by an end user. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```node const request: CreditEmploymentGetRequest = { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', }; try { const response = await client.creditEmploymentGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/credit/employment/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" }' ``` ```ruby request = Plaid::CreditEmploymentGetRequest.new( { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' } ) response = client.credit_employment_get(request) ``` ```java CreditEmploymentGetRequest request = new CreditEmploymentGetRequest() .userToken("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"); Response response = client .creditEmploymentGet(request) .execute(); ``` ```python request = CreditEmploymentGetRequest( user_token='user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' ) response = client.credit_employment_get(request) ``` ```go request := plaid.NewCreditEmploymentGetRequest( "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" ) response, _, err := client.PlaidApi.CreditEmploymentGet(ctx).CreditEmploymentGetRequest(*request).Execute() ``` #### Response fields  \[object\] Array of employment items. string The `item_id` of the Item associated with this webhook, warning, or error \[object\] nullable, string ID of the payroll provider account. nullable, string Current employment status. Possible values: `ACTIVE`, `INACTIVE`, `null` nullable, string Start of employment in ISO 8601 format (YYYY-MM-DD). Format: `date` nullable, string End of employment, if applicable. Provided in ISO 8601 format (YYY-MM-DD). Format: `date` object An object containing employer data. nullable, string Name of employer. nullable, string Current title of employee. object The object containing a set of ids related to an employee. nullable, string The ID of an employee as given by their employer. nullable, string The ID of an employee as given by their payroll. nullable, string The ID of the position of the employee. nullable, string The type of employment for the individual. `"FULL_TIME"`: A full-time employee. `"PART_TIME"`: A part-time employee. `"CONTRACTOR"`: An employee typically hired externally through a contracting group. `"TEMPORARY"`: A temporary employee. `"OTHER"`: The employee type is not one of the above defined types. Possible values: `FULL_TIME`, `PART_TIME`, `CONTRACTOR`, `TEMPORARY`, `OTHER`, `null` nullable, string The date of the employee's most recent paystub in ISO 8601 format (YYYY-MM-DD). Format: `date` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "items": [ { "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "employments": [ { "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9", "status": "ACTIVE", "start_date": "2020-01-01", "end_date": null, "employer": { "name": "Plaid Inc" }, "title": "Software Engineer", "platform_ids": { "employee_id": "1234567", "position_id": "8888", "payroll_id": "1234567" }, "employee_type": "FULL_TIME", "last_paystub_date": "2022-01-15" } ] } ], "request_id": "LhQf0THi8SH1yJm" } ``` \=\*=\*=\*= #### /credit/payroll\_income/parsing\_config/update  #### Update the parsing configuration for a document income verification  [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) updates the parsing configuration for a document income verification. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string The `item_id` of the Item associated with this webhook, warning, or error required, \[string\] The types of analysis to enable for the document income verification session Possible values: `ocr`, `risk_signals` ```bash -X POST https://sandbox.plaid.com/credit/payroll_income/parsing_config/update \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_token": "user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12", "parsing_config": ["fraud_risk"] }' ``` ```node const request: CreditPayrollIncomeParsingConfigUpdateRequest = { user_token: 'user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12', parsing_config: ['fraud_risk'], }; try { const response = await client.creditPayrollIncomeParsingConfigUpdate(request); } catch (error) { // handle error } ``` ```python request = CreditPayrollIncomeParsingConfigUpdateRequest( user_token='user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12', parsing_config=['fraud_risk'] ) response = client.credit_payroll_income_parsing_config_update(request) ``` ```ruby request = Plaid::CreditPayrollIncomeParsingConfigUpdateRequest.new( { user_token: 'user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12', parsing_config: ['fraud_risk'], } ) response = client.credit_payroll_income_parsing_config_update(request) ``` ```go request := plaid.NewCreditPayrollIncomeParsingConfigUpdateRequest( "user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12", []string{"fraud_risk"}, ) response, _, err := client.PlaidApi.CreditPayrollIncomeParsingConfigUpdate(ctx).CreditPayrollIncomeParsingConfigUpdateRequest(*request).Execute() ``` ```java CreditPayrollIncomeParsingConfigUpdateRequest request = new CreditPayrollIncomeParsingConfigUpdateRequest() .userToken("user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12") .parsingConfig(Arrays.asList("ocr")); Response response = client .creditPayrollIncomeParsingConfigUpdate(request) .execute(); ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "LhQf0THi8SH1yJm" } ``` \=\*=\*=\*= #### /credit/payroll\_income/refresh  #### Refresh a digital payroll income verification  [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) refreshes a given digital payroll income verification. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . object An optional object for `/credit/payroll_income/refresh` request options. \[string\] An array of `item_id`s to be refreshed. Each `item_id` should uniquely identify a payroll income item. If this field is not provided, all `item_id`s associated with the `user_token` will be refreshed. string The URL where Plaid will send the payroll income refresh webhook. ```node const request: CreditPayrollIncomeRefreshRequest = { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d', }; try { const response = await client.creditPayrollIncomeRefresh(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/credit/payroll_income/refresh \ -H 'Content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", "options": { "item_ids": [ "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", ] }, }' ``` ```ruby request = Plaid::CreditPayrollIncomeRefreshRequest.new( { user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' } ) response = client.credit_payroll_income_refresh(request) ``` ```java CreditPayrollIncomeRefreshRequest request = new CreditPayrollIncomeRefreshRequest() .userToken("user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"); Response response = client .CreditPayrollIncomeRefresh(request) .execute(); ``` ```python request = CreditPayrollIncomeRefreshRequest( user_token='user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' ) response = client.credit_payroll_income_refresh(request) ``` ```go request := plaid.NewPayrollIncomeRefreshRequest( "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", ) response, _, err := client.PlaidApi.CreditPayrollIncomeRefresh(ctx).CreditPayrollIncomeRefreshRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. string The verification refresh status. One of the following: `"USER_PRESENCE_REQUIRED"` User presence is required to refresh an income verification. `"SUCCESSFUL"` The income verification refresh was successful. `"NOT_FOUND"` No new data was found after the income verification refresh. Possible values: `USER_PRESENCE_REQUIRED`, `SUCCESSFUL`, `NOT_FOUND` Response Object ```json { "request_id": "nTkbCH41HYmpbm5", "verification_refresh_status": "USER_PRESENCE_REQUIRED" } ``` ### Webhooks  Income webhooks are sent to indicate when an income verification or document fraud risk evaluation has finished processing. \=\*=\*=\*= #### INCOME\_VERIFICATION  Fired when the status of an income verification instance has changed. This webhook is fired for both the Document and Payroll Income flows, but not the Bank Income flow. It will typically take several minutes for this webhook to fire after the end user has uploaded their documents in the Document Income flow. #### Properties  string `"INCOME"` string `INCOME_VERIFICATION` string The Item ID associated with the verification. string The Plaid `user_id` of the User associated with this webhook, warning, or error. string `VERIFICATION_STATUS_PROCESSING_COMPLETE`: The income verification processing has completed. This indicates that the documents have been parsed successfully or that the documents were not parsable. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the `/credit/payroll_income/get` endpoint and check the document metadata to see which documents were successfully parsed. `VERIFICATION_STATUS_PROCESSING_FAILED`: An unexpected internal error occurred when attempting to process the verification documentation. `VERIFICATION_STATUS_PENDING_APPROVAL`: (deprecated) The income verification has been sent to the user for review. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "INCOME", "webhook_code": "INCOME_VERIFICATION", "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ", "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334", "verification_status": "VERIFICATION_STATUS_PROCESSING_COMPLETE", "environment": "production" } ``` \=\*=\*=\*= #### INCOME\_VERIFICATION\_RISK\_SIGNALS  Fired when risk signals have been processed for documents uploaded via Document Income. It will typically take a minute or two for this webhook to fire after the end user has uploaded their documents in the Document Income flow. Once this webhook has fired, [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) may then be called to determine whether the documents were successfully processed and to retrieve risk data. #### Properties  string `"INCOME"` string `INCOME_VERIFICATION_RISK_SIGNALS` string The Item ID associated with the verification. string The Plaid `user_id` of the User associated with this webhook, warning, or error. string `RISK_SIGNALS_PROCESSING_COMPLETE`: The income verification fraud detection processing has completed. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the `/credit/payroll_income/risk_signals/get` endpoint to get all risk signal data. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "INCOME", "webhook_code": "INCOME_VERIFICATION_RISK_SIGNALS", "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ", "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334", "risk_signals_status": "RISK_SIGNALS_PROCESSING_COMPLETE", "environment": "production" } ``` \=\*=\*=\*= #### BANK\_INCOME\_REFRESH\_COMPLETE  Fired when a refreshed bank income report has finished generating or failed to generate. The [/credit/bank\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomerefresh) endpoint that previously triggered this webhook is deprecated; to refresh Bank Income data, send the user through Link Update Mode, or migrate to CRA Income Insights and call [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) for a backend refresh. To get this webhook, subscribe via the [Dashboard](https://dashboard.plaid.com/developers/webhooks) . #### Properties  string `INCOME` string `BANK_INCOME_REFRESH_COMPLETE` string The `user_id` corresponding to the user the webhook has fired for. string The result of the bank income refresh report generation `SUCCESS`: The refreshed report was successfully generated and can be retrieved via `/credit/bank_income/get`. `FAILURE`: The refreshed report failed to be generated Possible values: `SUCCESS`, `FAILURE` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "INCOME", "webhook_code": "BANK_INCOME_REFRESH_COMPLETE", "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "result": "SUCCESS", "environment": "production" } ``` \=\*=\*=\*= #### INCOME\_VERIFICATION\_REFRESH\_RECONNECT\_NEEDED  Fired when the attempt to refresh Payroll Income data for a user via [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) failed because the user must re-connect their payroll account. #### Properties  string `INCOME` string `INCOME_VERIFICATION_REFRESH_RECONNECT_NEEDED` string The `user_id` corresponding to the user the webhook has fired for. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "INCOME", "webhook_code": "INCOME_VERIFICATION_REFRESH_RECONNECT_NEEDED", "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "environment": "production" } ``` --- # API - Investments Move | Plaid Docs Investments Move  ================= #### API reference for Investments Move endpoints and webhooks  For how-to guidance, see the [Investments Move documentation](https://plaid.com/docs/investments-move/index.html.md) . | Endpoints | | | --- | --- | | [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) | Fetch investments data required for ACATS or ATON transfer | \=\*=\*=\*= #### /investments/auth/get  #### Get data needed to authorize an investments transfer  The [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) endpoint allows developers to receive user-authorized data to facilitate the transfer of holdings #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. object An optional object to filter `/investments/auth/get` results. \[string\] An array of `account_id`s to retrieve for the Item. An error will be returned if a provided `account_id` is not associated with the Item. ```bash curl -X POST https://sandbox.plaid.com/investments/auth/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node const request: InvestmentsAuthGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.investmentsAuthGet(request); const investmentsAuthData = response.data; } catch (error) { // handle error } ``` ```python request = InvestmentsAuthGetRequest(access_token=access_token) response = client.investments_auth_get(request) investmentsAuthData = response ``` ```java InvestmentsAuthGetRequest request = new InvestmentsAuthGetRequest() .accessToken(accessToken); Response response = client() .investmentsAuthGet(request) .execute(); ``` ```ruby request = Plaid::InvestmentsAuthGetRequest.new({ access_token: access_token }) response = client.investments_auth_get(request) ``` ```go request := plaid.NewInvestmentsAuthGetRequest(accessToken) resp, _, err := client.PlaidApi.InvestmentsAuthGet(ctx).InvestmentsAuthGetRequest(*request).Execute() ``` #### Response fields  \[object\] The accounts for which data is being retrieved string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account, including margin loan information for investment accounts. nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, number The total amount of borrowed funds in the account, as determined by the financial institution. For investment-type accounts, the margin balance is the total value of borrowed assets in the account, as presented by the institution. This is commonly referred to as margin or a loan. Format: `double` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] The holdings belonging to investment accounts associated with the Item. Details of the securities in the holdings are provided in the `securities` field. string The Plaid `account_id` associated with the holding. string The Plaid `security_id` associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The `security_id` for the same security will typically be the same across different institutions, but this is not guaranteed. The `security_id` does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. number The last price given by the institution for this security. Format: `double` nullable, string The date at which `institution_price` was current. Format: `date` nullable, string Date and time at which `institution_price` was current, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). Format: `date-time` number The value of the holding, as reported by the institution. Format: `double` nullable, number The total cost basis of the holding (e.g., the total amount spent to acquire all assets currently in the holding). Format: `double` number The total quantity of the asset held, as reported by the financial institution. If the security is an option, `quantity` will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts. Format: `double` nullable, string The ISO-4217 currency code of the holding. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the holding. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, number The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with [equities](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-type) . Format: `double` nullable, number The value of the vested holdings as reported by the institution. Format: `double` \[object\] Objects describing the securities held in the accounts associated with the Item. string A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the `security_id` is case sensitive. The `security_id` may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. nullable, string 12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . nullable, string 9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . deprecated, nullable, string (Deprecated) 7-character SEDOL, an identifier assigned to securities in the UK. nullable, string An identifier given to the security by the institution nullable, string If `institution_security_id` is present, this field indicates the Plaid `institution_id` of the institution to whom the identifier belongs. nullable, string In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security. nullable, string A descriptive name for the security, suitable for display. nullable, string The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available. nullable, boolean Indicates that a security is a highly liquid asset and can be treated like cash. nullable, string The security type of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security type. Valid security types are: `cash`: Cash, currency, and money market funds `cryptocurrency`: Digital or virtual currencies `derivative`: Options, warrants, and other derivative instruments `equity`: Domestic and foreign equities `etf`: Multi-asset exchange-traded investment funds `fixed income`: Bonds and certificates of deposit (CDs) `loan`: Loans and loan receivables `mutual fund`: Open- and closed-end vehicles pooling funds of multiple investors `other`: Unknown or other investment types nullable, string The security subtype of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security subtype. Possible values: `asset backed security`, `bill`, `bond`, `bond with warrants`, `cash`, `cash management bill`, `common stock`, `convertible bond`, `convertible equity`, `cryptocurrency`, `depositary receipt`, `depositary receipt on debt`, `etf`, `float rating note`, `fund of funds`, `hedge fund`, `limited partnership unit`, `medium term note`, `money market debt`, `mortgage backed security`, `municipal bond`, `mutual fund`, `note`, `option`, `other`, `preferred convertible`, `preferred equity`, `private equity fund`, `real estate investment trust`, `structured equity product`, `treasury inflation protected securities`, `unit`, `warrant`. nullable, number Price of the security at the close of the previous trading session. Null for non-public securities. If the security is a foreign currency this field will be updated daily and will be priced in USD. If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to `update_datetime` with the time when the price was last updated. Format: `double` nullable, string Date for which `close_price` is accurate. Always `null` if `close_price` is `null`. Format: `date` nullable, string Date and time at which `close_price` is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always `null` if `close_price` is `null`. Format: `date-time` nullable, string The ISO-4217 currency code of the price given. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the security. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The ISO-10383 Market Identifier Code of the exchange or market in which the security is being traded. nullable, string The sector classification of the security, such as Finance, Health Technology, etc. For a complete list of possible values, please refer to the ["Sectors and Industries" spreadsheet](https://docs.google.com/spreadsheets/d/1L7aXUdqLhxgM8qe7hK67qqKXiUdQqILpwZ0LpxvCVnc) . nullable, string The industry classification of the security, such as Biotechnology, Airlines, etc. For a complete list of possible values, please refer to the ["Sectors and Industries" spreadsheet](https://docs.google.com/spreadsheets/d/1L7aXUdqLhxgM8qe7hK67qqKXiUdQqILpwZ0LpxvCVnc) . nullable, string The ISO-10962 Classification of Financial Instruments Code used to classify the security based on its structure and function. nullable, object Details about the option security. For the Sandbox environment, this data is currently only available if the Item is using a [custom Sandbox user](https://plaid.com/docs/sandbox/user-custom/index.html.md) and the `ticker` field of the custom security follows the [OCC Option Symbol](https://en.wikipedia.org/wiki/Option_symbol#The_OCC_Option_Symbol) standard with no spaces. For an example of simulating this in Sandbox, see the [custom Sandbox GitHub](https://github.com/plaid/sandbox-custom-users) . string The type of this option contract. It is one of: `put`: for Put option contracts `call`: for Call option contracts string The expiration date for this option contract, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` number The strike price for this option contract, per share of security. Format: `double` string The ticker of the underlying security for this option contract. nullable, object Details about the fixed income security. nullable, object Details about a fixed income security's expected rate of return. number The fixed income security's expected rate of return. Format: `double` nullable, string The type of rate which indicates how the predicted yield was calculated. It is one of: `coupon`: the annualized interest rate for securities with a one-year term or longer, such as treasury notes and bonds. `coupon_equivalent`: the calculated equivalent for the annualized interest rate factoring in the discount rate and time to maturity, for shorter term, non-interest-bearing securities such as treasury bills. `discount`: the rate at which the present value or cost is discounted from the future value upon maturity, also known as the face value. `yield`: the total predicted rate of return factoring in both the discount rate and the coupon rate, applicable to securities such as exchange-traded bonds which can both be interest-bearing as well as sold at a discount off its face value. Possible values: `coupon`, `coupon_equivalent`, `discount`, `yield`, `null` nullable, string The maturity date for this fixed income security, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` nullable, string The issue date for this fixed income security, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` nullable, number The face value that is paid upon maturity of the fixed income security, per unit of security. Format: `double` \[object\] Information about the account owners for the accounts associated with the Item. string The ID of the account that this identity information pertains to \[string\] A list of names associated with the account by the financial institution. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's `names` array. object Identifying information for transferring holdings to an investments account. \[object\] string The Plaid account ID associated with the account numbers string The full account number for the account \[string\] Identifiers for the clearinghouses that are associated with the account in order of relevance. If this array is empty, call `/institutions/get_by_id` with the `item.institution_id` to get the DTC number. \[object\] string The Plaid account ID associated with the account numbers string The full account number for the account \[object\] string The Plaid account ID associated with the account numbers string The plan number for the employer's 401k retirement plan string The full account number for the account object Object with metadata pertaining to the source of data for the account numbers, owners, and holdings that are returned. string A description of the source of data for a given product/data type. `INSTITUTION`: The institution supports this product, and the data was provided by the institution. `INSTITUTION_MASK`: The user manually provided the full account number, which was matched to the account mask provided by the institution. Only applicable to the `numbers` data type. `USER`: The institution does not support this product, and the data was manually provided by the user. Possible values: `INSTITUTION`, `INSTITUTION_MASK`, `USER` string A description of the source of data for a given product/data type. `INSTITUTION`: The institution supports this product, and the data was provided by the institution. `INSTITUTION_MASK`: The user manually provided the full account number, which was matched to the account mask provided by the institution. Only applicable to the `numbers` data type. `USER`: The institution does not support this product, and the data was manually provided by the user. Possible values: `INSTITUTION`, `INSTITUTION_MASK`, `USER` string A description of the source of data for a given product/data type. `INSTITUTION`: The institution supports this product, and the data was provided by the institution. `INSTITUTION_MASK`: The user manually provided the full account number, which was matched to the account mask provided by the institution. Only applicable to the `numbers` data type. `USER`: The institution does not support this product, and the data was manually provided by the user. Possible values: `INSTITUTION`, `INSTITUTION_MASK`, `USER` object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "accounts": [ { "account_id": "31qEA6LPwGumkA4Z5mGbfyGwr4mL6nSZlQqpZ", "balances": { "available": 43200, "current": 43200, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "4444", "name": "Plaid Money Market", "official_name": "Plaid Platinum Standard 1.85% Interest Money Market", "subtype": "money market", "type": "depository" }, { "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "balances": { "available": null, "current": 415.57, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "5555", "name": "Plaid IRA", "official_name": null, "subtype": "ira", "type": "investment" } ], "holdings": [ { "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "cost_basis": 1, "institution_price": 1, "institution_price_as_of": "2021-05-25", "institution_price_datetime": null, "institution_value": 0.01, "iso_currency_code": "USD", "quantity": 0.01, "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are", "unofficial_currency_code": null, "vested_quantity": 1, "vested_value": 1 }, { "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "cost_basis": 0.01, "institution_price": 0.011, "institution_price_as_of": "2021-05-25", "institution_price_datetime": null, "institution_value": 110, "iso_currency_code": "USD", "quantity": 10000, "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "cost_basis": 94.808, "institution_price": 94.808, "institution_price_as_of": "2021-04-13", "institution_price_datetime": null, "institution_value": 94.808, "iso_currency_code": "USD", "quantity": 1, "security_id": "Lxe4yz4XQEtwb2YArO7RFMpPDvPxy7FALRyea", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "cost_basis": 40, "institution_price": 42.15, "institution_price_as_of": "2021-05-25", "institution_price_datetime": null, "institution_value": 210.75, "iso_currency_code": "USD", "quantity": 5, "security_id": "abJamDazkgfvBkVGgnnLUWXoxnomp5up8llg4", "unofficial_currency_code": null, "vested_quantity": 7, "vested_value": 66 } ], "item": { "available_products": [ "assets", "balance", "beacon", "cra_base_report", "cra_income_insights", "signal", "identity", "identity_match", "income", "income_verification", "investments", "processor_identity", "recurring_transactions", "transactions" ], "billed_products": [ "investments_auth" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_115616", "institution_name": "Vanguard", "item_id": "7qBnDwLP3aIZkD7NKZ5ysk5X9xVxDWHg65oD5", "products": [ "investments_auth" ], "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook" }, "numbers": { "acats": [ { "account": "TR5555", "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "dtc_numbers": [ "1111", "2222", "3333" ] } ] }, "owners": [ { "account_id": "31qEA6LPwGumkA4Z5mGbfyGwr4mL6nSZlQqpZ", "names": [ "Alberta Bobbeth Charleson" ] }, { "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "names": [ "Alberta Bobbeth Charleson" ] } ], "request_id": "hPCXou4mm9Qwzzu", "securities": [ { "close_price": 0.011, "close_price_as_of": null, "cusip": null, "cfi_code": "OCASPS", "industry": null, "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "market_identifier_code": null, "name": "Nflx Feb 01'18 $355 Call", "option_contract": null, "fixed_income": null, "proxy_security_id": null, "sector": null, "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb", "sedol": null, "ticker_symbol": "NFLX180201C00355000", "type": "derivative", "subtype": "option", "unofficial_currency_code": null, "update_datetime": null }, { "close_price": 94.808, "close_price_as_of": "2023-11-02", "cusip": "912797HE0", "cfi_code": "DYZTXR", "fixed_income": { "face_value": 100, "issue_date": "2023-11-02", "maturity_date": "2024-10-31", "yield_rate": { "percentage": 5.43, "type": "coupon_equivalent" } }, "industry": "Sovereign Government", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "market_identifier_code": null, "name": "US Treasury Bill - 5.43% 31/10/2024 USD 100", "option_contract": null, "proxy_security_id": null, "sector": "Government", "security_id": "Lxe4yz4XQEtwb2YArO7RFMpPDvPxy7FALRyea", "sedol": null, "ticker_symbol": null, "type": "fixed income", "subtype": "bill", "unofficial_currency_code": null, "update_datetime": null }, { "close_price": 9.08, "close_price_as_of": "2024-09-09", "cusip": null, "cfi_code": "CIOIBS", "fixed_income": null, "industry": "Investment Trusts or Mutual Funds", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "market_identifier_code": null, "name": "DoubleLine Total Return Bond I", "option_contract": null, "proxy_security_id": null, "sector": "Miscellaneous", "security_id": "AE5rBXra1AuZLE34rkvvIyG8918m3wtRzElnJ", "sedol": null, "ticker_symbol": "DBLTX", "type": "mutual fund", "subtype": "mutual fund", "unofficial_currency_code": null, "update_datetime": null }, { "close_price": 42.15, "close_price_as_of": null, "cusip": null, "cfi_code": "CEOIES", "fixed_income": null, "industry": null, "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "market_identifier_code": null, "name": "iShares Inc MSCI Brazil", "option_contract": null, "proxy_security_id": null, "sector": null, "security_id": "abJamDazkgfvBkVGgnnLUWXoxnomp5up8llg4", "sedol": null, "ticker_symbol": "EWZ", "type": "etf", "subtype": "etf", "unofficial_currency_code": null, "update_datetime": null }, { "close_price": 1, "close_price_as_of": null, "cusip": null, "cfi_code": null, "fixed_income": null, "industry": null, "institution_id": null, "institution_security_id": null, "is_cash_equivalent": true, "isin": null, "iso_currency_code": "USD", "market_identifier_code": null, "name": "U S Dollar", "option_contract": null, "proxy_security_id": null, "sector": null, "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are", "sedol": null, "ticker_symbol": null, "type": "cash", "subtype": "cash", "unofficial_currency_code": null, "update_datetime": null } ], "data_sources": { "numbers": "INSTITUTION", "owners": "INSTITUTION", "holdings": "INSTITUTION" } } ``` --- # API - Investments | Plaid Docs Investments  ============ #### API reference for Investments endpoints and webhooks  For how-to guidance, see the [Investments documentation](https://plaid.com/docs/investments/index.html.md) . | Endpoints | | | --- | --- | | [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) | Fetch investment holdings | | [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) | Fetch investment transactions | | [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) | Refresh investment transactions | | See also | | | --- | --- | | [/processor/investments/holdings/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentsholdingsget) | Fetch Investments Holdings data | | [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) | Fetch Investments Transactions data | | Webhooks | | | --- | --- | | [HOLDINGS: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#holdings-default_update) | New holdings available | | [INVESTMENTS\_TRANSACTIONS: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#investments_transactions-default_update) | New transactions available | | [INVESTMENTS\_TRANSACTIONS: HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#investments_transactions-historical_update) | Investments data ready | ### Endpoints  \=\*=\*=\*= #### /investments/holdings/get  #### Get Investment holdings  The [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) endpoint allows developers to receive user-authorized stock position data for `investment`\-type accounts. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. object An optional object to filter `/investments/holdings/get` results. If provided, must not be `null`. \[string\] An array of `account_id`s to retrieve for the Item. An error will be returned if a provided `account_id` is not associated with the Item. ```go holdingsGetReq := plaid.NewInvestmentsHoldingsGetRequest("ACCESS_TOKEN") holdingsGetReqOptions := plaid.NewInvestmentHoldingsGetRequestOptions() holdingsGetReqOptions.SetAccountIds([]string{"ACCOUNT_ID"}) holdingsGetReq.SetOptions(*holdingsGetReqOptions) holdingsGetResp, _, err = client.PlaidApi.InvestmentsHoldingsGet(ctx).InvestmentsHoldingsGetRequest( *holdingsGetReq, ).Execute() securities := holdingsGetResp.GetSecurities() holdings := holdingsGetResp.GetHoldings() ``` ```node // Pull Holdings for an Item const request: InvestmentsHoldingsGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.investmentsHoldingsGet(request); const holdings = response.data.holdings; const securities = response.data.securities; } catch (error) { // handle error } ``` ```python # Pull Holdings for an Item request = InvestmentsHoldingsGetRequest(access_token=access_token) response = client.investments_holdings_get(request) # Handle Holdings response holdings = response['holdings'] # Handle Securities response securities = response['securities'] ``` ```ruby # Pull Holdings for an Item request = Plaid::InvestmentsHoldingsGetRequest.new({ access_token: access_token }) response = client.investments_holdings_get(request) # Handle Holdings response holdings = response.holdings # Handle Securities response securities = response.securities ``` ```java // Pull Holdings for an Item InvestmentsHoldingsGetRequest request = new InvestmentsHoldingsGetRequest() .accessToken(accessToken); Response response = client() .investmentsHoldingsGet(request) .execute(); // Handle Holdings response List holdings = response.body().getHoldings(); // Handle Securities response List securities = response.body().getSecurities(); ``` ```bash curl -X POST https://sandbox.plaid.com/investments/holdings/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": string }' ``` #### Response fields  \[object\] The accounts associated with the Item string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account, including margin loan information for investment accounts. nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, number The total amount of borrowed funds in the account, as determined by the financial institution. For investment-type accounts, the margin balance is the total value of borrowed assets in the account, as presented by the institution. This is commonly referred to as margin or a loan. Format: `double` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] The holdings belonging to investment accounts associated with the Item. Details of the securities in the holdings are provided in the `securities` field. string The Plaid `account_id` associated with the holding. string The Plaid `security_id` associated with the holding. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. The `security_id` for the same security will typically be the same across different institutions, but this is not guaranteed. The `security_id` does not typically change, but may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. number The last price given by the institution for this security. Format: `double` nullable, string The date at which `institution_price` was current. Format: `date` nullable, string Date and time at which `institution_price` was current, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). Format: `date-time` number The value of the holding, as reported by the institution. Format: `double` nullable, number The total cost basis of the holding (e.g., the total amount spent to acquire all assets currently in the holding). Format: `double` number The total quantity of the asset held, as reported by the financial institution. If the security is an option, `quantity` will reflect the total number of options (typically the number of contracts multiplied by 100), not the number of contracts. Format: `double` nullable, string The ISO-4217 currency code of the holding. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the holding. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, number The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with [equities](https://plaid.com/docs/api/products/investments/index.html.md#investments-holdings-get-response-securities-type) . Format: `double` nullable, number The value of the vested holdings as reported by the institution. Format: `double` \[object\] Objects describing the securities held in the accounts associated with the Item. string A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the `security_id` is case sensitive. The `security_id` may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. nullable, string 12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . nullable, string 9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . deprecated, nullable, string (Deprecated) 7-character SEDOL, an identifier assigned to securities in the UK. nullable, string An identifier given to the security by the institution nullable, string If `institution_security_id` is present, this field indicates the Plaid `institution_id` of the institution to whom the identifier belongs. nullable, string In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security. nullable, string A descriptive name for the security, suitable for display. nullable, string The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available. nullable, boolean Indicates that a security is a highly liquid asset and can be treated like cash. nullable, string The security type of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security type. Valid security types are: `cash`: Cash, currency, and money market funds `cryptocurrency`: Digital or virtual currencies `derivative`: Options, warrants, and other derivative instruments `equity`: Domestic and foreign equities `etf`: Multi-asset exchange-traded investment funds `fixed income`: Bonds and certificates of deposit (CDs) `loan`: Loans and loan receivables `mutual fund`: Open- and closed-end vehicles pooling funds of multiple investors `other`: Unknown or other investment types nullable, string The security subtype of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security subtype. Possible values: `asset backed security`, `bill`, `bond`, `bond with warrants`, `cash`, `cash management bill`, `common stock`, `convertible bond`, `convertible equity`, `cryptocurrency`, `depositary receipt`, `depositary receipt on debt`, `etf`, `float rating note`, `fund of funds`, `hedge fund`, `limited partnership unit`, `medium term note`, `money market debt`, `mortgage backed security`, `municipal bond`, `mutual fund`, `note`, `option`, `other`, `preferred convertible`, `preferred equity`, `private equity fund`, `real estate investment trust`, `structured equity product`, `treasury inflation protected securities`, `unit`, `warrant`. nullable, number Price of the security at the close of the previous trading session. Null for non-public securities. If the security is a foreign currency this field will be updated daily and will be priced in USD. If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to `update_datetime` with the time when the price was last updated. Format: `double` nullable, string Date for which `close_price` is accurate. Always `null` if `close_price` is `null`. Format: `date` nullable, string Date and time at which `close_price` is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always `null` if `close_price` is `null`. Format: `date-time` nullable, string The ISO-4217 currency code of the price given. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the security. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The ISO-10383 Market Identifier Code of the exchange or market in which the security is being traded. nullable, string The sector classification of the security, such as Finance, Health Technology, etc. For a complete list of possible values, please refer to the ["Sectors and Industries" spreadsheet](https://docs.google.com/spreadsheets/d/1L7aXUdqLhxgM8qe7hK67qqKXiUdQqILpwZ0LpxvCVnc) . nullable, string The industry classification of the security, such as Biotechnology, Airlines, etc. For a complete list of possible values, please refer to the ["Sectors and Industries" spreadsheet](https://docs.google.com/spreadsheets/d/1L7aXUdqLhxgM8qe7hK67qqKXiUdQqILpwZ0LpxvCVnc) . nullable, string The ISO-10962 Classification of Financial Instruments Code used to classify the security based on its structure and function. nullable, object Details about the option security. For the Sandbox environment, this data is currently only available if the Item is using a [custom Sandbox user](https://plaid.com/docs/sandbox/user-custom/index.html.md) and the `ticker` field of the custom security follows the [OCC Option Symbol](https://en.wikipedia.org/wiki/Option_symbol#The_OCC_Option_Symbol) standard with no spaces. For an example of simulating this in Sandbox, see the [custom Sandbox GitHub](https://github.com/plaid/sandbox-custom-users) . string The type of this option contract. It is one of: `put`: for Put option contracts `call`: for Call option contracts string The expiration date for this option contract, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` number The strike price for this option contract, per share of security. Format: `double` string The ticker of the underlying security for this option contract. nullable, object Details about the fixed income security. nullable, object Details about a fixed income security's expected rate of return. number The fixed income security's expected rate of return. Format: `double` nullable, string The type of rate which indicates how the predicted yield was calculated. It is one of: `coupon`: the annualized interest rate for securities with a one-year term or longer, such as treasury notes and bonds. `coupon_equivalent`: the calculated equivalent for the annualized interest rate factoring in the discount rate and time to maturity, for shorter term, non-interest-bearing securities such as treasury bills. `discount`: the rate at which the present value or cost is discounted from the future value upon maturity, also known as the face value. `yield`: the total predicted rate of return factoring in both the discount rate and the coupon rate, applicable to securities such as exchange-traded bonds which can both be interest-bearing as well as sold at a discount off its face value. Possible values: `coupon`, `coupon_equivalent`, `discount`, `yield`, `null` nullable, string The maturity date for this fixed income security, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` nullable, string The issue date for this fixed income security, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` nullable, number The face value that is paid upon maturity of the fixed income security, per unit of security. Format: `double` object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. boolean When true, this field indicates that the Item's portfolio was manually created with the Investments Fallback flow. Response Object ```json { "accounts": [ { "account_id": "5Bvpj4QknlhVWk7GygpwfVKdd133GoCxB814g", "balances": { "available": 43200, "current": 43200, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "4444", "name": "Plaid Money Market", "official_name": "Plaid Platinum Standard 1.85% Interest Money Market", "subtype": "money market", "type": "depository" }, { "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1", "balances": { "available": null, "current": 110.01, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "5555", "name": "Plaid IRA", "official_name": null, "subtype": "ira", "type": "investment" }, { "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm", "balances": { "available": null, "current": 24580.0605, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "6666", "name": "Plaid 401k", "official_name": null, "subtype": "401k", "type": "investment" }, { "account_id": "ax0xgOBYRAIqOOjeLZr0iZBb8r6K88HZXpvmq", "balances": { "available": 48200.03, "current": 48200.03, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "4092", "name": "Plaid Crypto Exchange Account", "official_name": null, "subtype": "crypto exchange", "type": "investment" } ], "holdings": [ { "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1", "cost_basis": 1, "institution_price": 1, "institution_price_as_of": "2021-04-13", "institution_price_datetime": null, "institution_value": 0.01, "iso_currency_code": "USD", "quantity": 0.01, "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm", "cost_basis": 1.5, "institution_price": 2.11, "institution_price_as_of": "2021-04-13", "institution_price_datetime": null, "institution_value": 2.11, "iso_currency_code": "USD", "quantity": 1, "security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm", "cost_basis": 10, "institution_price": 10.42, "institution_price_as_of": "2021-04-13", "institution_price_datetime": null, "institution_value": 20.84, "iso_currency_code": "USD", "quantity": 2, "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1", "cost_basis": 0.01, "institution_price": 0.011, "institution_price_as_of": "2021-04-13", "institution_price_datetime": null, "institution_value": 110, "iso_currency_code": "USD", "quantity": 10000, "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm", "cost_basis": 23, "institution_price": 27, "institution_price_as_of": "2021-04-13", "institution_price_datetime": null, "institution_value": 636.309, "iso_currency_code": "USD", "quantity": 23.567, "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm", "cost_basis": 15, "institution_price": 13.73, "institution_price_as_of": "2021-04-13", "institution_price_datetime": null, "institution_value": 1373.6865, "iso_currency_code": "USD", "quantity": 100.05, "security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm", "cost_basis": 948.08, "institution_price": 94.808, "institution_price_as_of": "2021-04-13", "institution_price_datetime": null, "institution_value": 948.08, "iso_currency_code": "USD", "quantity": 10, "security_id": "Lxe4yz4XQEtwb2YArO7RFMpPDvPxy7FALRyea", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm", "cost_basis": 1, "institution_price": 1, "institution_price_as_of": "2021-04-13", "institution_price_datetime": null, "institution_value": 12345.67, "iso_currency_code": "USD", "quantity": 12345.67, "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "ax0xgOBYRAIqOOjeLZr0iZBb8r6K88HZXpvmq", "cost_basis": 92.47, "institution_price": 0.177494362, "institution_price_as_of": "2022-01-14", "institution_price_datetime": "2022-06-07T23:01:00Z", "institution_value": 4437.35905, "iso_currency_code": "USD", "quantity": 25000, "security_id": "vLRMV3MvY1FYNP91on35CJD5QN5rw9Fpa9qOL", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null } ], "item": { "available_products": [ "balance", "identity", "liabilities", "transactions" ], "billed_products": [ "assets", "auth", "investments" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_3", "institution_name": "Chase", "item_id": "4z9LPae1nRHWy8pvg9jrsgbRP4ZNQvIdbLq7g", "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook", "auth_method": "INSTANT_AUTH" }, "request_id": "l68wb8zpS0hqmsJ", "securities": [ { "close_price": 0.011, "close_price_as_of": "2021-04-13", "cusip": null, "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "name": "Nflx Feb 01'18 $355 Call", "proxy_security_id": null, "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb", "sedol": null, "ticker_symbol": "NFLX180201C00355000", "type": "derivative", "subtype": "option", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": "XNAS", "sector": "Technology Services", "industry": "Internet Software or Services", "cfi_code": "OCASPS", "option_contract": { "contract_type": "call", "expiration_date": "2018-02-01", "strike_price": 355, "underlying_security_ticker": "NFLX" }, "fixed_income": null }, { "close_price": 27, "close_price_as_of": null, "cusip": "577130834", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US5771308344", "iso_currency_code": "USD", "name": "Matthews Pacific Tiger Fund Insti Class", "proxy_security_id": null, "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP", "sedol": null, "ticker_symbol": "MIPTX", "type": "mutual fund", "subtype": "mutual fund", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": "XNAS", "sector": "Miscellaneous", "industry": "Investment Trusts or Mutual Funds", "cfi_code": "CIOGES", "option_contract": null, "fixed_income": null }, { "close_price": 2.11, "close_price_as_of": null, "cusip": "00448Q201", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US00448Q2012", "iso_currency_code": "USD", "name": "Achillion Pharmaceuticals Inc.", "proxy_security_id": null, "security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy", "sedol": null, "ticker_symbol": "ACHN", "type": "equity", "subtype": "common stock", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": "XNAS", "sector": "Health Technology", "industry": "Major Pharmaceuticals", "cfi_code": "ESVUFR", "option_contract": null, "fixed_income": null }, { "close_price": 10.42, "close_price_as_of": null, "cusip": "258620103", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US2586201038", "iso_currency_code": "USD", "name": "DoubleLine Total Return Bond Fund", "proxy_security_id": null, "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk", "sedol": null, "ticker_symbol": "DBLTX", "type": "mutual fund", "subtype": "mutual fund", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": "XNAS", "sector": null, "industry": null, "cfi_code": "CIOIBS", "option_contract": null, "fixed_income": null }, { "close_price": 1, "close_price_as_of": null, "cusip": null, "institution_id": null, "institution_security_id": null, "is_cash_equivalent": true, "isin": null, "iso_currency_code": "USD", "name": "U S Dollar", "proxy_security_id": null, "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are", "sedol": null, "ticker_symbol": "USD", "type": "cash", "subtype": "cash", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": null, "sector": null, "industry": null, "cfi_code": null, "option_contract": null, "fixed_income": null }, { "close_price": 13.73, "close_price_as_of": null, "cusip": null, "institution_id": "ins_3", "institution_security_id": "NHX105509", "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "name": "NH PORTFOLIO 1055 (FIDELITY INDEX)", "proxy_security_id": null, "security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN", "sedol": null, "ticker_symbol": "NHX105509", "type": "etf", "subtype": "etf", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": "XNAS", "sector": null, "industry": null, "cfi_code": null, "option_contract": null, "fixed_income": null }, { "close_price": 94.808, "close_price_as_of": "2023-11-02", "cusip": "912797HE0", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "name": "US Treasury Bill - 5.43% 31/10/2024 USD 100", "proxy_security_id": null, "security_id": "Lxe4yz4XQEtwb2YArO7RFMpPDvPxy7FALRyea", "sedol": null, "ticker_symbol": null, "type": "fixed income", "subtype": "bill", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": null, "sector": "Government", "industry": "Sovereign Government", "cfi_code": "DYZTXR", "option_contract": null, "fixed_income": { "face_value": 100, "issue_date": "2023-11-02", "maturity_date": "2024-10-31", "yield_rate": { "percentage": 5.43, "type": "coupon_equivalent" } } }, { "close_price": 0.140034616, "close_price_as_of": "2022-01-24", "cusip": null, "institution_id": "ins_3", "institution_security_id": null, "is_cash_equivalent": true, "isin": null, "iso_currency_code": "USD", "name": "Dogecoin", "proxy_security_id": null, "security_id": "vLRMV3MvY1FYNP91on35CJD5QN5rw9Fpa9qOL", "sedol": null, "ticker_symbol": "DOGE", "type": "cryptocurrency", "subtype": "cryptocurrency", "unofficial_currency_code": null, "update_datetime": "2022-06-07T23:01:00Z", "market_identifier_code": "XNAS", "sector": null, "industry": null, "cfi_code": null, "option_contract": null, "fixed_income": null } ] } ``` \=\*=\*=\*= #### /investments/transactions/get  #### Get investment transactions  The [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) endpoint allows developers to retrieve up to 24 months of user-authorized transaction data for investment accounts. Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift. Due to the potentially large number of investment transactions associated with an Item, results are paginated. Manipulate the count and offset parameters in conjunction with the `total_investment_transactions` response body field to fetch all available investment transactions. Note that Investments does not have a webhook to indicate when initial transaction data has loaded (unless you use the `async_update` option). Instead, if transactions data is not ready when [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) is first called, Plaid will wait for the data. For this reason, calling [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) immediately after Link may take up to one to two minutes to return. Data returned by the asynchronous investments extraction flow (when `async_update` is set to true) may not be immediately available to [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) . To be alerted when the data is ready to be fetched, listen for the `HISTORICAL_UPDATE` webhook. If no investments history is ready when [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) is called, it will return a `PRODUCT_NOT_READY` error. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. required, string The earliest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. Format: `date` required, string The most recent date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. Format: `date` object An optional object to filter `/investments/transactions/get` results. If provided, must be non-`null`. \[string\] An array of `account_ids` to retrieve for the Item. integer The number of transactions to fetch. Default: `100` Minimum: `1` Maximum: `500` integer The number of transactions to skip when fetching transaction history Default: `0` Minimum: `0` boolean If the Item was not initialized with the investments product via the `products`, `required_if_supported_products`, or `optional_products` array when calling `/link/token/create`, and `async_update` is set to true, the initial Investments extraction will happen asynchronously. Plaid will subsequently fire a `HISTORICAL_UPDATE` webhook when the extraction completes. When `false`, Plaid will wait to return a response until extraction completion and no `HISTORICAL_UPDATE` webhook will fire. Note that while the extraction is happening asynchronously, calls to `/investments/transactions/get` and `/investments/refresh` will return `PRODUCT_NOT_READY` errors until the extraction completes. Default: `false` ```bash curl -X POST https://sandbox.plaid.com/investments/transactions/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": string, "start_date": "2018-03-01", "end_date": "2018-04-30", "options": { "count": 250, "offset": 100 } }' ``` ```ruby # Pull investment transactions for a date range request = Plaid::InvestmentsTransactionsGetRequest.new( { access_token: access_token, start_date: '2019-03-01', end_date: '2019-04-30' } ) response = client.investments_transactions_get(request) investmentTransactions = response.investment_transactions # Manipulate the offset parameter to paginate transactions # and retrieve all available data while investmentTransactions.length < response.total_investment_transactions request = Plaid::InvestmentsTransactionsGetRequest.new( { access_token: access_token, start_date: '2018-01-01', end_date: '2018-02-01', options: { offset: investmentTransactions.length } } ) response = client.investments_transactions_get(request) investmentTransactions += response.investment_transactions end ``` ```java SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd"); startDate = simpleDateFormat.parse("2019-03-01"); endDate = simpleDateFormat.parse("2019-04-30"); // Pull transactions for a date range InvestmentsTransactionsGetRequest request = new InvestmentsTransactionsGetRequest() .accessToken(accessToken) .startDate(startDate) .endDate(endDate); Response response = client().investmentsTransactionsGet(request).execute(); // Manipulate the count and offset parameters to paginate // transactions and retrieve all available data InvestmentsTransactionsGetRequestOptions options = new InvestmentsTransactionsGetRequestOptions() .count(100) .offset(1) .accountIds(Arrays.asList(someAccountId)); InvestmentsTransactionsGetRequest request = new InvestmentsTransactionsGetRequest() .accessToken(getItemPublicTokenExchangeResponse().getAccessToken()) .startDate(startDate) .endDate(endDate) .options(options); Response response = client().investmentsTransactionsGet(request).execute(); for (InvestmentsTransactionsGetResponse.InvestmentTransaction txn : response.body().getInvestmentTransactions()) { ... } ``` ```node const request: InvestmentsTransactionsGetRequest = { access_token: accessToken, start_date: '2019-01-01', end_date: '2019-06-10', }; try { const response = await plaidClient.investmentsTransactionsGet(request); const investmentTransactions = response.data.investment_transactions; } catch (error) { // handle error } ``` ```python request = InvestmentsTransactionsGetRequest( access_token=access_token, start_date=date.fromisoformat('2019-03-01'), end_date=date.fromisoformat('2019-04-30'), options=InvestmentsTransactionsGetRequestOptions() ) response = client.investments_transactions_get(request) investment_transactions = response['investment_transactions'] # Manipulate the count and offset parameters to paginate # transactions and retrieve all available data while len(investment_transactions) < response['total_investment_transactions']: request = InvestmentsTransactionsGetRequest( access_token=access_token, start_date=date.fromisoformat('2019-03-01'), end_date=date.fromisoformat('2019-04-30'), options=InvestmentsTransactionsGetRequestOptions( offset=len(investment_transactions) ) ) response = client.investments_transactions_get(request) investment_transactions.extend(response['investment_transactions']) ``` ```go request := plaid.NewInvestmentsTransactionsGetRequest(accessToken, startDateString, endDateString) response, _, err := client.PlaidApi.InvestmentsTransactionsGet(ctx).InvestmentsTransactionsGetRequest(*request).Execute() investmentTransactions := response.GetInvestmentTransactions() ``` #### Response fields  object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` \[object\] The accounts for which transaction history is being fetched. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account, including margin loan information for investment accounts. nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, number The total amount of borrowed funds in the account, as determined by the financial institution. For investment-type accounts, the margin balance is the total value of borrowed assets in the account, as presented by the institution. This is commonly referred to as margin or a loan. Format: `double` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] All securities for which there is a corresponding transaction being fetched. string A unique, Plaid-specific identifier for the security, used to associate securities with holdings. Like all Plaid identifiers, the `security_id` is case sensitive. The `security_id` may change if inherent details of the security change due to a corporate action, for example, in the event of a ticker symbol change or CUSIP change. nullable, string 12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . nullable, string 9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please start the verification process [here](https://docs.google.com/forms/d/e/1FAIpQLSd9asHEYEfmf8fxJTHZTAfAzW4dugsnSu-HS2J51f1mxwd6Sw/viewform) . deprecated, nullable, string (Deprecated) 7-character SEDOL, an identifier assigned to securities in the UK. nullable, string An identifier given to the security by the institution nullable, string If `institution_security_id` is present, this field indicates the Plaid `institution_id` of the institution to whom the identifier belongs. nullable, string In certain cases, Plaid will provide the ID of another security whose performance resembles this security, typically when the original security has low volume, or when a private security can be modeled with a publicly traded security. nullable, string A descriptive name for the security, suitable for display. nullable, string The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available. nullable, boolean Indicates that a security is a highly liquid asset and can be treated like cash. nullable, string The security type of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security type. Valid security types are: `cash`: Cash, currency, and money market funds `cryptocurrency`: Digital or virtual currencies `derivative`: Options, warrants, and other derivative instruments `equity`: Domestic and foreign equities `etf`: Multi-asset exchange-traded investment funds `fixed income`: Bonds and certificates of deposit (CDs) `loan`: Loans and loan receivables `mutual fund`: Open- and closed-end vehicles pooling funds of multiple investors `other`: Unknown or other investment types nullable, string The security subtype of the holding. In rare instances, a null value is returned when institutional data is insufficient to determine the security subtype. Possible values: `asset backed security`, `bill`, `bond`, `bond with warrants`, `cash`, `cash management bill`, `common stock`, `convertible bond`, `convertible equity`, `cryptocurrency`, `depositary receipt`, `depositary receipt on debt`, `etf`, `float rating note`, `fund of funds`, `hedge fund`, `limited partnership unit`, `medium term note`, `money market debt`, `mortgage backed security`, `municipal bond`, `mutual fund`, `note`, `option`, `other`, `preferred convertible`, `preferred equity`, `private equity fund`, `real estate investment trust`, `structured equity product`, `treasury inflation protected securities`, `unit`, `warrant`. nullable, number Price of the security at the close of the previous trading session. Null for non-public securities. If the security is a foreign currency this field will be updated daily and will be priced in USD. If the security is a cryptocurrency, this field will be updated multiple times a day. As crypto prices can fluctuate quickly and data may become stale sooner than other asset classes, refer to `update_datetime` with the time when the price was last updated. Format: `double` nullable, string Date for which `close_price` is accurate. Always `null` if `close_price` is `null`. Format: `date` nullable, string Date and time at which `close_price` is accurate, in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ). Always `null` if `close_price` is `null`. Format: `date-time` nullable, string The ISO-4217 currency code of the price given. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the security. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The ISO-10383 Market Identifier Code of the exchange or market in which the security is being traded. nullable, string The sector classification of the security, such as Finance, Health Technology, etc. For a complete list of possible values, please refer to the ["Sectors and Industries" spreadsheet](https://docs.google.com/spreadsheets/d/1L7aXUdqLhxgM8qe7hK67qqKXiUdQqILpwZ0LpxvCVnc) . nullable, string The industry classification of the security, such as Biotechnology, Airlines, etc. For a complete list of possible values, please refer to the ["Sectors and Industries" spreadsheet](https://docs.google.com/spreadsheets/d/1L7aXUdqLhxgM8qe7hK67qqKXiUdQqILpwZ0LpxvCVnc) . nullable, string The ISO-10962 Classification of Financial Instruments Code used to classify the security based on its structure and function. nullable, object Details about the option security. For the Sandbox environment, this data is currently only available if the Item is using a [custom Sandbox user](https://plaid.com/docs/sandbox/user-custom/index.html.md) and the `ticker` field of the custom security follows the [OCC Option Symbol](https://en.wikipedia.org/wiki/Option_symbol#The_OCC_Option_Symbol) standard with no spaces. For an example of simulating this in Sandbox, see the [custom Sandbox GitHub](https://github.com/plaid/sandbox-custom-users) . string The type of this option contract. It is one of: `put`: for Put option contracts `call`: for Call option contracts string The expiration date for this option contract, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` number The strike price for this option contract, per share of security. Format: `double` string The ticker of the underlying security for this option contract. nullable, object Details about the fixed income security. nullable, object Details about a fixed income security's expected rate of return. number The fixed income security's expected rate of return. Format: `double` nullable, string The type of rate which indicates how the predicted yield was calculated. It is one of: `coupon`: the annualized interest rate for securities with a one-year term or longer, such as treasury notes and bonds. `coupon_equivalent`: the calculated equivalent for the annualized interest rate factoring in the discount rate and time to maturity, for shorter term, non-interest-bearing securities such as treasury bills. `discount`: the rate at which the present value or cost is discounted from the future value upon maturity, also known as the face value. `yield`: the total predicted rate of return factoring in both the discount rate and the coupon rate, applicable to securities such as exchange-traded bonds which can both be interest-bearing as well as sold at a discount off its face value. Possible values: `coupon`, `coupon_equivalent`, `discount`, `yield`, `null` nullable, string The maturity date for this fixed income security, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` nullable, string The issue date for this fixed income security, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date` nullable, number The face value that is paid upon maturity of the fixed income security, per unit of security. Format: `double` \[object\] The transactions being fetched string The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the `investment_transaction_id` is case sensitive. string The `account_id` of the account against which this transaction posted. nullable, string The `security_id` to which this transaction is related. string The [ISO 8601](https://wikipedia.org/wiki/ISO_8601) posting date for the transaction. This is typically the settlement date. Format: `date` nullable, string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) representing when the order type was initiated. This field is returned for select financial institutions and reflects the value provided by the institution. Format: `date-time` string The institution’s description of the transaction. number The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions. Format: `double` number The complete value of the transaction. Positive values when cash is debited, e.g. purchases of stock; negative values when cash is credited, e.g. sales of stock. Treatment remains the same for cash-only movements unassociated with securities. Format: `double` number The price of the security at which this transaction occurred. Format: `double` nullable, number The combined value of all fees applied to this transaction Format: `double` string Value is one of the following: `buy`: Buying an investment `sell`: Selling an investment `cancel`: A cancellation of a pending transaction `cash`: Activity that modifies a cash position `fee`: A fee on the account `transfer`: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer For descriptions of possible transaction types and subtypes, see the [Investment transaction types schema](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Possible values: `buy`, `sell`, `cancel`, `cash`, `fee`, `transfer` string For descriptions of possible transaction types and subtypes, see the [Investment transaction types schema](https://plaid.com/docs/api/accounts/index.html.md#investment-transaction-types-schema) . Possible values: `account fee`, `adjustment`, `assignment`, `buy`, `buy to cover`, `contribution`, `deposit`, `distribution`, `dividend`, `dividend reinvestment`, `exercise`, `expire`, `fund fee`, `interest`, `interest receivable`, `interest reinvestment`, `legal fee`, `loan payment`, `long-term capital gain`, `long-term capital gain reinvestment`, `management fee`, `margin expense`, `merger`, `miscellaneous fee`, `non-qualified dividend`, `non-resident tax`, `pending credit`, `pending debit`, `qualified dividend`, `rebalance`, `return of principal`, `request`, `sell`, `sell short`, `send`, `short-term capital gain`, `short-term capital gain reinvestment`, `spin off`, `split`, `stock distribution`, `tax`, `tax withheld`, `trade`, `transfer`, `transfer fee`, `trust fee`, `unqualified gain`, `withdrawal` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-`null`. nullable, string The unofficial currency code associated with the holding. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. integer The total number of transactions available within the date range specified. If `total_investment_transactions` is larger than the size of the `transactions` array, more transactions are available and can be fetched via manipulating the `offset` parameter. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. boolean When true, this field indicates that the Item's portfolio was manually created with the Investments Fallback flow. Response Object ```json { "accounts": [ { "account_id": "5e66Dl6jNatx3nXPGwZ7UkJed4z6KBcZA4Rbe", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" }, { "account_id": "KqZZMoZmBWHJlz7yKaZjHZb78VNpaxfVa7e5z", "balances": { "available": null, "current": 320.76, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "5555", "name": "Plaid IRA", "official_name": null, "subtype": "ira", "type": "investment" }, { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "balances": { "available": null, "current": 23631.9805, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "6666", "name": "Plaid 401k", "official_name": null, "subtype": "401k", "type": "investment" } ], "investment_transactions": [ { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "amount": -8.72, "cancel_transaction_id": null, "date": "2020-05-29", "transaction_datetime": null, "fees": 0, "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW", "iso_currency_code": "USD", "name": "INCOME DIV DIVIDEND RECEIVED", "price": 0, "quantity": 0, "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ", "subtype": "dividend", "type": "cash", "unofficial_currency_code": null }, { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "amount": -1289.01, "cancel_transaction_id": null, "date": "2020-05-28", "transaction_datetime": "2020-05-28T15:10:09Z", "fees": 7.99, "investment_transaction_id": "pK99jB9e7mtwjA435GpVuMvmWQKVbVFLWme57", "iso_currency_code": "USD", "name": "SELL Matthews Pacific Tiger Fund Insti Class", "price": 27.53, "quantity": -47.74104242992852, "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP", "subtype": "sell", "type": "sell", "unofficial_currency_code": null }, { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "amount": 7.7, "cancel_transaction_id": null, "date": "2020-05-27", "transaction_datetime": "2020-05-27T17:23:22Z", "fees": 7.99, "investment_transaction_id": "LKoo1ko93wtreBwM7yQnuQ3P5DNKbKSPRzBNv", "iso_currency_code": "USD", "name": "BUY DoubleLine Total Return Bond Fund", "price": 10.42, "quantity": 0.7388014749727547, "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk", "subtype": "buy", "type": "buy", "unofficial_currency_code": null } ], "item": { "available_products": [ "assets", "balance", "identity", "transactions" ], "billed_products": [ "auth", "investments" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_12", "item_id": "8Mqq5rqQ7Pcxq9MGDv3JULZ6yzZDLMCwoxGDq", "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook" }, "request_id": "iv4q3ZlytOOthkv", "securities": [ { "close_price": 27, "close_price_as_of": null, "cusip": "577130834", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US5771308344", "iso_currency_code": "USD", "name": "Matthews Pacific Tiger Fund Insti Class", "proxy_security_id": null, "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP", "sedol": null, "ticker_symbol": "MIPTX", "type": "mutual fund", "subtype": "mutual fund", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": "XNAS", "sector": "Miscellaneous", "industry": "Investment Trusts or Mutual Funds", "cfi_code": "CIOGES", "option_contract": null, "fixed_income": null }, { "close_price": 10.42, "close_price_as_of": null, "cusip": "258620103", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US2586201038", "iso_currency_code": "USD", "name": "DoubleLine Total Return Bond Fund", "proxy_security_id": null, "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk", "sedol": null, "ticker_symbol": "DBLTX", "type": "mutual fund", "subtype": "mutual fund", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": "XNAS", "sector": null, "industry": null, "cfi_code": "CIOIBS", "option_contract": null, "fixed_income": null }, { "close_price": 34.73, "close_price_as_of": null, "cusip": "84470P109", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US84470P1093", "iso_currency_code": "USD", "name": "Southside Bancshares Inc.", "proxy_security_id": null, "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ", "sedol": null, "ticker_symbol": "SBSI", "type": "equity", "subtype": "common stock", "unofficial_currency_code": null, "update_datetime": null, "market_identifier_code": "XNAS", "sector": "Finance", "industry": "Regional Banks", "cfi_code": "ESVUFR", "option_contract": null, "fixed_income": null } ], "total_investment_transactions": 3 } ``` \=\*=\*=\*= #### /investments/refresh  #### Refresh investment data  [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) is an optional endpoint for users of the Investments product. It initiates an on-demand extraction to fetch the newest investment holdings and transactions for an Item. This on-demand extraction takes place in addition to the periodic extractions that automatically occur one or more times per day for any Investments-enabled Item. If changes to investments are discovered after calling [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) , Plaid will fire webhooks: [HOLDINGS: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#holdings-default_update) if any new holdings are detected, and [INVESTMENTS\_TRANSACTIONS: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#investments_transactions-default_update) if any new investment transactions are detected. This webhook will typically not fire in the Sandbox environment, due to the lack of dynamic investment transactions and holdings data. To test this webhook in Sandbox, call [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) . Updated holdings and investment transactions can be fetched by calling [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) and [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) . Note that the [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) endpoint is not supported by all institutions. If called on an Item from an institution that does not support this functionality, it will return a `PRODUCT_NOT_SUPPORTED` error. As this endpoint triggers a synchronous request for fresh data, latency may be higher than for other Plaid endpoints (typically less than 10 seconds, but occasionally up to 30 seconds or more); if you encounter errors, you may find it necessary to adjust your timeout period when making requests. [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) is offered as an add-on to Investments and has a separate [fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/team/products) or contact your Plaid account manager. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string The access token associated with the Item data is being requested for. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```bash curl -X POST https://sandbox.plaid.com/investments/refresh \ -H 'content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, }' ``` ```node const request: InvestmentsRefreshRequest = { access_token: accessToken, }; try { await plaidClient.investmentsRefresh(request); } catch (error) { // handle error } ``` ```ruby request = Plaid::InvestmentsRefreshRequest.new({ access_token: access_token }) response = client.investments_refresh(request) ``` ```java InvestmentsRefreshRequest request = new InvestmentsRefreshRequest() .accessToken(accessToken); Response response = client() .investmentsRefresh(request) .execute(); ``` ```python request = InvestmentsRefreshRequest(access_token=access_token) response = client.investments_refresh(request) ``` ```go request := plaid.NewInvestmentsRefreshRequest(accessToken) response, _, err := client.PlaidApi.InvestmentsRefresh(ctx).InvestmentsRefreshRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "1vwmF5TBQwiqfwP" } ``` ### Webhooks  Updates are sent to indicate that new holdings or investment transactions are available. \=\*=\*=\*= #### HOLDINGS: DEFAULT\_UPDATE  Fired when new or updated holdings have been detected on an investment account. The webhook typically fires in response to any newly added holdings or price changes to existing holdings, most commonly after market close. #### Properties  string `HOLDINGS` string `DEFAULT_UPDATE` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. number The number of new holdings reported since the last time this webhook was fired. number The number of updated holdings reported since the last time this webhook was fired. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "HOLDINGS", "webhook_code": "DEFAULT_UPDATE", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "user_id": "usr_9nSp2KuZ2x4JDw", "error": null, "new_holdings": 19, "updated_holdings": 0, "environment": "production" } ``` \=\*=\*=\*= #### INVESTMENTS\_TRANSACTIONS: DEFAULT\_UPDATE  Fired when new transactions have been detected on an investment account. #### Properties  string `INVESTMENTS_TRANSACTIONS` string `DEFAULT_UPDATE` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. number The number of new transactions reported since the last time this webhook was fired. number The number of canceled transactions reported since the last time this webhook was fired. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "INVESTMENTS_TRANSACTIONS", "webhook_code": "DEFAULT_UPDATE", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "user_id": "usr_9nSp2KuZ2x4JDw", "error": null, "new_investments_transactions": 16, "cancelled_investments_transactions": 0, "environment": "production" } ``` \=\*=\*=\*= #### INVESTMENTS\_TRANSACTIONS: HISTORICAL\_UPDATE  Fired after an asynchronous extraction on an investments account. #### Properties  string `INVESTMENTS_TRANSACTIONS` string `HISTORICAL_UPDATE` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. number The number of new transactions reported since the last time this webhook was fired. number The number of canceled transactions reported since the last time this webhook was fired. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "INVESTMENTS_TRANSACTIONS", "webhook_code": "HISTORICAL_UPDATE", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "user_id": "usr_9nSp2KuZ2x4JDw", "error": null, "new_investments_transactions": 16, "cancelled_investments_transactions": 0, "environment": "production" } ``` --- # API - Plaid Layer | Plaid Docs Layer  ====== #### API reference for Layer endpoints  For how-to guidance, see the [Layer documentation](https://plaid.com/docs/layer/index.html.md) . | Endpoints | | | --- | --- | | [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) | Creates a Link token for a Layer session | | [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) | Returns user permissioned account data | | Webhooks | | | --- | --- | | [LAYER\_AUTHENTICATION\_PASSED](https://plaid.com/docs/api/products/layer/index.html.md#layer_authentication_passed) | A user has been authenticated | | [SESSION\_FINISHED](https://plaid.com/docs/api/products/layer/index.html.md#session_finished) | A Layer session has finished | ### Endpoints  \=\*=\*=\*= #### /session/token/create  #### Create a Link token for Layer  [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) is used to create a Link token for Layer. The returned Link token is used as an parameter when initializing the Link SDK. For more details, see the [Link flow overview](https://plaid.com/docs/link/index.html.md#link-flow-overview) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The id of a template defined in Plaid Dashboard object Details about the end user. Required if a root-level `user_id` is not provided. required, string A unique ID representing the end user. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. It is currently used as a means of searching logs for the given user in the Plaid Dashboard. string The `user_id` created by calling `/user/create`. Provide this field only if you are using Plaid Check Report with Layer and have a `user_token`. string A URI indicating the destination where a user should be forwarded after completing the Link flow; used to support OAuth authentication flows when launching Link in the browser or another app. The `redirect_uri` should not contain any query parameters. When used in Production, must be an https URI. Note that any redirect URI must also be added to the Allowed redirect URIs list in the [developer dashboard](https://dashboard.plaid.com/team/api) . If initializing on Android, `android_package_name` must be specified instead and `redirect_uri` should be left blank. string The name of your app's Android package. Required if using the session token to initialize Layer on Android. Any package name specified here must also be added to the Allowed Android package names setting on the [developer dashboard](https://dashboard.plaid.com/team/api) . When creating a session token for initializing Layer on other platforms, `android_package_name` must be left blank and `redirect_uri` should be used instead. string The destination URL to which any webhooks should be sent. If you use the same webhook listener for all Sandbox or all Production activity, set this value in the Layer template editor in the Dashboard instead. Only provide a value in this field if you need to use multiple webhook URLs per environment (an uncommon use case). If provided, a value in this field will take priority over webhook values set in the Layer template editor. Format: `url` string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```node const request: SessionTokenCreateRequest = { user: { client_user_id: 'user-abc' }, template_id: 'template_4uinBNe4B2x9' }; try { const response = await client.sessionTokenCreate(request); const linkToken = response.data.link.link_token; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/session/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user": { "client_user_id": "user-abc" }, "template_id": "template_4uinBNe4B2x9" }' ``` ```ruby request = Plaid::SessionTokenCreateRequest.new( { user: { client_user_id: 'user-abc' }, template_id: 'template_4uinBNe4B2x9' } ) response = client.session_token_create(request) link_token = response.link.link_token ``` ```java SessionTokenCreateRequestUser user = new SessionTokenCreateRequestUser() .clientUserId("user-abc"); SessionTokenCreateRequest request = new SessionTokenCreateRequest() .user(user) .templateId("template_4uinBNe4B2x9"); Response response = client() .sessionTokenCreate(request) .execute(); String linkToken = response.body().getLink().getLinkToken(); ``` ```python request = SessionTokenCreateRequest( user=SessionTokenCreateRequestUser( client_user_id='user-abc' ), template_id='template_4uinBNe4B2x9' ) response = client.session_token_create(request) link_token = response['link']['link_token'] ``` ```go user := plaid.SessionTokenCreateRequestUser{ ClientUserId: "user-abc", } request := plaid.NewSessionTokenCreateRequest( user, "template_4uinBNe4B2x9", ) response, _, err := client.PlaidApi. SessionTokenCreate(ctx). SessionTokenCreateRequest(*request). Execute() if err != nil { panic(err) } linkToken := response.GetLink().GetLinkToken(); ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. object Response data for `/session/token/create` intended for use with the Link SDK. string A Link token, which can be supplied to Link in order to initialize it and receive a `public_token`. string The expiration date for the `link_token`, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. A `link_token` created to generate a `public_token` that will be exchanged for a new `access_token` expires after 4 hours. A `link_token` created for an existing Item (such as when updating an existing `access_token` by launching Link in update mode) expires after 30 minutes. Format: `date-time` string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . Response Object ```json { "link": { "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176", "expiration": "2020-03-27T12:56:34Z" }, "request_id": "XQVgFigpGHXkb0b" } ``` \=\*=\*=\*= #### /user\_account/session/get  #### Retrieve User Account  This endpoint returns user permissioned account data, including identity and Item access tokens, for use with [Plaid Layer](https://plaid.com/docs/layer/index.html.md) . Note that end users are permitted to edit the prefilled identity data in the Link flow before sharing it with you; you should treat any identity data returned by this endpoint as user-submitted, unverified data. For a verification layer, you can add [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) to your flow, or check the submitted identity data against bank account data from linked accounts using [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The public token generated by the end user Layer session. ```node const request: UserAccountSessionGetRequest = { public_token: 'profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d', }; try { const response = await client.userAccountSessionGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/user_account/session/get \ -H 'Content-Type: application/json' \ -d '{ "public_token": "profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d", "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}" }' ``` ```ruby request = Plaid::UserAccountSessionGetRequest.new( { public_token: 'profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d' } ) response = client.user_account_session_get(request) ``` ```java UserAccountSessionGetRequest request = new UserAccountSessionGetRequest() .publicToken("profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d"); Response response = client() .userAccountSessionGet(request) .execute(); ``` ```python request = UserAccountSessionGetRequest( public_token=PublicToken('profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d') ) response = client.user_account_session_get(request) ``` ```go request := plaid.NewUserAccountSessionGetRequest( "profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d", ) response, _, err := client.PlaidApi. UserAccountSessionGet(ctx). UserAccountSessionGetRequest(*request). Execute() ``` #### Response fields  nullable, object The identity data permissioned by the end user during the authorization flow. nullable, object The user's first name and last name. string string nullable, object The user's address. nullable, string The full city name nullable, string The region or state. Example: `"NC"` nullable, string The full street address Example: `"564 Main Street, APT 15"` nullable, string The second line street address nullable, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code string The user's phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format nullable, string The user's email address. Note: email is currently not returned. nullable, string The user's date of birth. nullable, string The user's social security number. nullable, string The last 4 digits of the user's social security number. \[object\] string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. string The access token associated with the Item data is being requested for. nullable, object Statistics tracking the number of edits made to identity fields over various time periods. object Edit counts over various time periods. integer Number of edits in the current session integer Number of edits in the last 1 day integer Number of edits in the last 30 days integer Number of edits in the last 365 days integer Total number of edits object Edit counts over various time periods. integer Number of edits in the current session integer Number of edits in the last 1 day integer Number of edits in the last 30 days integer Number of edits in the last 365 days integer Total number of edits object Edit counts over various time periods. integer Number of edits in the current session integer Number of edits in the last 1 day integer Number of edits in the last 30 days integer Number of edits in the last 365 days integer Total number of edits object Edit counts over various time periods. integer Number of edits in the current session integer Number of edits in the last 1 day integer Number of edits in the last 30 days integer Number of edits in the last 365 days integer Total number of edits nullable, object Official identity document edit statistics. object Edit counts over various time periods. integer Number of edits in the current session integer Number of edits in the last 1 day integer Number of edits in the last 30 days integer Number of edits in the last 365 days integer Total number of edits string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "identity": { "name": { "first_name": "Leslie", "last_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "", "city": "Pawnee", "region": "IN", "postal_code": "41006", "country": "US" }, "email": "leslie@knope.com", "phone_number": "+14157452130", "date_of_birth": "1975-01-18", "ssn": "987654321", "ssn_last_4": "4321" }, "identity_edit_history": { "name": { "edits_current": 0, "edits_1d": 0, "edits_30d": 1, "edits_365d": 1, "edits_all_time": 1 }, "address": { "edits_current": 1, "edits_1d": 1, "edits_30d": 2, "edits_365d": 2, "edits_all_time": 2 }, "email": { "edits_current": 0, "edits_1d": 0, "edits_30d": 0, "edits_365d": 0, "edits_all_time": 0 }, "date_of_birth": { "edits_current": 0, "edits_1d": 0, "edits_30d": 0, "edits_365d": 0, "edits_all_time": 0 }, "official_document": { "ssn": { "edits_current": 0, "edits_1d": 0, "edits_30d": 0, "edits_365d": 0, "edits_all_time": 0 } } }, "items": [ { "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr", "access_token": "access-sandbox-435beced-94e8-4df3-a181-1dde1cfa19f0" } ], "request_id": "m8MDnv9okwxFNBV" } ``` ### Webhooks  \=\*=\*=\*= #### LAYER\_AUTHENTICATION\_PASSED  Indicates that Plaid's authentication process has completed for a user and that Plaid has verified that the user owns their phone number. If you receive this webhook, you should skip your own OTP phone number verification flow for the user, even if the user does not complete the entire Link flow. If the user doesn't complete the full Link flow (as verified by your being able to successfully call [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) using the `public_token` from the `onSuccess` callback) it is recommended that you implement [webhook verification](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md) or another technique to avoid webhook spoofing attacks. #### Properties  string `LAYER` string `LAYER_AUTHENTICATION_PASSED` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` string An identifier for the Link session these events occurred in string The Link token used to create the Link session these events are from API Object ```json { "webhook_type": "LAYER", "webhook_code": "LAYER_AUTHENTICATION_PASSED", "environment": "production", "link_session_id": "1daca4d5-9a0d-4e85-a2e9-1e905ecaa32e", "link_token": "link-sandbox-79e723b0-0e04-4248-8a33-15ceb6828a45" } ``` \=\*=\*=\*= #### SESSION\_FINISHED  Contains the state of a completed Link session, along with the public token(s) if available. By default, this webhook is sent only for sessions enabled for the Hosted Link flow (including Link Recovery flows), a Multi-Item Link flow, or a Layer flow. If you would like to receive this webhook for other sessions, contact your Account Manager or Support. This enablement will also enable the `EVENTS` webhook for all Link sessions and the ability to use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to retrieve events for non-Hosted-Link sessions. #### Properties  string `LINK` string `SESSION_FINISHED` string The final status of the Link session. Will always be "SUCCESS" or "EXITED". string The identifier for the Link session. string The link token used to create the Link session. deprecated, string The public token generated by the Link session. This field has been deprecated; please use `public_tokens` instead. \[string\] The public tokens generated by the Link session. string The Plaid `user_id` of the User associated with this webhook, warning, or error. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "LINK", "webhook_code": "SESSION_FINISHED", "status": "SUCCESS", "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171", "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176", "public_tokens": [ "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" ], "environment": "sandbox" } ``` --- # API - Liabilities | Plaid Docs Liabilities  ============ #### API reference for Liabilities endpoints and webhooks  For how-to guidance, see the [Liabilities documentation](https://plaid.com/docs/liabilities/index.html.md) . | Endpoints | | | --- | --- | | [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) | Fetch liabilities data | | Webhooks | | | --- | --- | | [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/liabilities/index.html.md#default_update) | New or updated liabilities available | ### Endpoints  \=\*=\*=\*= #### /liabilities/get  #### Retrieve Liabilities data  The [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) endpoint returns various details about an Item with loan or credit accounts. Liabilities data is available primarily for US financial institutions, with some limited coverage of Canadian institutions. Currently supported account types are account type `credit` with account subtype `credit card` or `paypal`, and account type `loan` with account subtype `student` or `mortgage`. To limit accounts listed in Link to types and subtypes supported by Liabilities, you can use the `account_filters` parameter when [creating a Link token](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . The types of information returned by Liabilities can include balances and due dates, loan terms, and account details such as original loan amount and guarantor. Data is refreshed approximately once per day; the latest data can be retrieved by calling [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. object An optional object to filter `/liabilities/get` results. If provided, `options` cannot be null. \[string\] A list of accounts to retrieve for the Item. An error will be returned if a provided `account_id` is not associated with the Item ```bash curl -X POST https://sandbox.plaid.com/liabilities/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node // Retrieve Liabilities data for an Item const request: LiabilitiesGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.liabilitiesGet(request); const liabilities = response.data.liabilities; } catch (error) { // handle error } ``` ```python # retrieve Liabilities data for an item request = LiabilitiesGetRequest(access_token=access_token) response = client.liabilities_get(request) liabilities = response['liabilities'] ``` ```java // Retrieve Liabilities data for an Item LiabilitiesGetRequest request = new LiabilitiesGetRequest() .accessToken(accessToken); Response response = client() .liabilitiesGet(request) .execute(); Liabilities liabilities = response.body().getLiabilities(); ``` ```ruby # retrieve Liabilities data for an item request = Plaid::LiabilitiesGetRequest.new({ access_token: access_token }) response = client.liabilities_get(request) liabilities = response.liabilities ``` ```go request := plaid.NewLiabilitiesGetRequest(accessToken) resp, _, err := client.PlaidApi.LiabilitiesGet(ctx).LiabilitiesGetRequest(*request).Execute() liabilities := resp.GetLiabilities() ``` #### Response fields  \[object\] An array of accounts associated with the Item string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` object An object containing liability accounts nullable, \[object\] The credit accounts returned. nullable, string The ID of the account that this liability belongs to. \[object\] The various interest rates that apply to the account. APR information is not provided by all card issuers; if APR data is not available, this array will be empty. number Annual Percentage Rate applied. Format: `double` string The type of balance to which the APR applies. Possible values: `balance_transfer_apr`, `cash_apr`, `purchase_apr`, `special` nullable, number Amount of money that is subjected to the APR if a balance was carried beyond payment due date. How it is calculated can vary by card issuer. It is often calculated as an average daily balance. Format: `double` nullable, number Amount of money charged due to interest from last statement. Format: `double` nullable, boolean true if a payment is currently overdue. Availability for this field is limited. nullable, number The amount of the last payment. Format: `double` nullable, string The date of the last payment. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Availability for this field is limited. Format: `date` nullable, string The date of the last statement. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, number The total amount owed as of the last statement issued Format: `double` nullable, number The minimum payment due for the next billing cycle. Format: `double` nullable, string The due date for the next payment. The due date is `null` if a payment is not expected. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, \[object\] The mortgage accounts returned. string The ID of the account that this liability belongs to. nullable, string The account number of the loan. nullable, number The current outstanding amount charged for late payment. Format: `double` nullable, number Total amount held in escrow to pay taxes and insurance on behalf of the borrower. Format: `double` nullable, boolean Indicates whether the borrower has private mortgage insurance in effect. nullable, boolean Indicates whether the borrower will pay a penalty for early payoff of mortgage. object Object containing metadata about the interest rate for the mortgage. nullable, number Percentage value (interest rate of current mortgage, not APR) of interest payable on a loan. Format: `double` nullable, string The type of interest charged (fixed or variable). nullable, number The amount of the last payment. Format: `double` nullable, string The date of the last payment. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string Description of the type of loan, for example `conventional`, `fixed`, or `variable`. This field is provided directly from the loan servicer and does not have an enumerated set of possible values. nullable, string Full duration of mortgage as at origination (e.g. `10 year`). nullable, string Original date on which mortgage is due in full. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, number The amount of the next payment. Format: `double` nullable, string The due date for the next payment. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The date on which the loan was initially lent. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, number The original principal balance of the mortgage. Format: `double` nullable, number Amount of loan (principal + interest) past due for payment. Format: `double` object Object containing fields describing property address. nullable, string The city name. nullable, string The ISO 3166-1 alpha-2 country code. nullable, string The five or nine digit postal code. nullable, string The region or state (example "NC"). nullable, string The full street address (example "564 Main Street, Apt 15"). nullable, number The year to date (YTD) interest paid. Format: `double` nullable, number The YTD principal paid. Format: `double` nullable, \[object\] The student loan accounts returned. nullable, string The ID of the account that this liability belongs to. Each account can only contain one liability. nullable, string The account number of the loan. For some institutions, this may be a masked version of the number (e.g., the last 4 digits instead of the entire number). nullable, \[string\] The dates on which loaned funds were disbursed or will be disbursed. These are often in the past. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The date when the student loan is expected to be paid off. Availability for this field is limited. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The guarantor of the student loan. number The interest rate on the loan as a percentage. Format: `double` nullable, boolean `true` if a payment is currently overdue. Availability for this field is limited. nullable, number The amount of the last payment. Format: `double` nullable, string The date of the last payment. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, number The total amount owed as of the last statement issued Format: `double` nullable, string The date of the last statement. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The type of loan, e.g., "Consolidation Loans". object An object representing the status of the student loan nullable, string The date until which the loan will be in its current status. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The status type of the student loan Possible values: `cancelled`, `charged off`, `claim`, `consolidated`, `deferment`, `delinquent`, `discharged`, `extension`, `forbearance`, `in grace`, `in military`, `in school`, `not fully disbursed`, `other`, `paid in full`, `refunded`, `repayment`, `transferred`, `pending idr` nullable, number The minimum payment due for the next billing cycle. There are some exceptions: Some institutions require a minimum payment across all loans associated with an account number. Our API presents that same minimum payment amount on each loan. The institutions that do this are: Great Lakes ( `ins_116861`), Firstmark (`ins_116295`), Commonbond Firstmark Services (`ins_116950`), Granite State (`ins_116308`), and Oklahoma Student Loan Authority (`ins_116945`). Firstmark (`ins_116295` ) and Navient (`ins_116248`) will display as $0 if there is an autopay program in effect. Format: `double` nullable, string The due date for the next payment. The due date is `null` if a payment is not expected. A payment is not expected if `loan_status.type` is `deferment`, `in_school`, `consolidated`, `paid in full`, or `transferred`. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, string The date on which the loan was initially lent. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Format: `date` nullable, number The original principal balance of the loan. Format: `double` nullable, number The total dollar amount of the accrued interest balance. For Sallie Mae ( `ins_116944`), this amount is included in the current balance of the loan, so this field will return as `null`. Format: `double` nullable, string The relevant account number that should be used to reference this loan for payments. In the majority of cases, `payment_reference_number` will match `account_number,` but in some institutions, such as Great Lakes (`ins_116861`), it will be different. object An object representing the repayment plan for the student loan nullable, string The description of the repayment plan as provided by the servicer. nullable, string The type of the repayment plan. Possible values: `extended graduated`, `extended standard`, `graduated`, `income-contingent repayment`, `income-based repayment`, `income-sensitive repayment`, `interest-only`, `other`, `pay as you earn`, `revised pay as you earn`, `standard`, `saving on a valuable education`, `null` nullable, string The sequence number of the student loan. Heartland ECSI (`ins_116948`) does not make this field available. object The address of the student loan servicer. This is generally the remittance address to which payments should be sent. nullable, string The full city name nullable, string The region or state Example: `"NC"` nullable, string The full street address Example: `"564 Main Street, APT 15"` nullable, string The postal code nullable, string The ISO 3166-1 alpha-2 country code nullable, number The year to date (YTD) interest paid. Availability for this field is limited. Format: `double` nullable, number The year to date (YTD) principal paid. Availability for this field is limited. Format: `double` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "accounts": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" }, { "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "balances": { "available": null, "current": 410, "iso_currency_code": "USD", "limit": 2000, "unofficial_currency_code": null }, "mask": "3333", "name": "Plaid Credit Card", "official_name": "Plaid Diamond 12.5% APR Interest Credit Card", "subtype": "credit card", "type": "credit" }, { "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE", "balances": { "available": null, "current": 65262, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "7777", "name": "Plaid Student Loan", "official_name": null, "subtype": "student", "type": "loan" }, { "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J", "balances": { "available": null, "current": 56302.06, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "8888", "name": "Plaid Mortgage", "official_name": null, "subtype": "mortgage", "type": "loan" } ], "item": { "available_products": [ "balance", "investments" ], "billed_products": [ "assets", "auth", "identity", "liabilities", "transactions" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_3", "institution_name": "Chase", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook", "auth_method": "INSTANT_AUTH" }, "liabilities": { "credit": [ { "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "aprs": [ { "apr_percentage": 15.24, "apr_type": "balance_transfer_apr", "balance_subject_to_apr": 1562.32, "interest_charge_amount": 130.22 }, { "apr_percentage": 27.95, "apr_type": "cash_apr", "balance_subject_to_apr": 56.22, "interest_charge_amount": 14.81 }, { "apr_percentage": 12.5, "apr_type": "purchase_apr", "balance_subject_to_apr": 157.01, "interest_charge_amount": 25.66 }, { "apr_percentage": 0, "apr_type": "special", "balance_subject_to_apr": 1000, "interest_charge_amount": 0 } ], "is_overdue": false, "last_payment_amount": 168.25, "last_payment_date": "2019-05-22", "last_statement_issue_date": "2019-05-28", "last_statement_balance": 1708.77, "minimum_payment_amount": 20, "next_payment_due_date": "2020-05-28" } ], "mortgage": [ { "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J", "account_number": "3120194154", "current_late_fee": 25, "escrow_balance": 3141.54, "has_pmi": true, "has_prepayment_penalty": true, "interest_rate": { "percentage": 3.99, "type": "fixed" }, "last_payment_amount": 3141.54, "last_payment_date": "2019-08-01", "loan_term": "30 year", "loan_type_description": "conventional", "maturity_date": "2045-07-31", "next_monthly_payment": 3141.54, "next_payment_due_date": "2019-11-15", "origination_date": "2015-08-01", "origination_principal_amount": 425000, "past_due_amount": 2304, "property_address": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "ytd_interest_paid": 12300.4, "ytd_principal_paid": 12340.5 } ], "student": [ { "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE", "account_number": "4277075694", "disbursement_dates": [ "2002-08-28" ], "expected_payoff_date": "2032-07-28", "guarantor": "DEPT OF ED", "interest_rate_percentage": 5.25, "is_overdue": false, "last_payment_amount": 138.05, "last_payment_date": "2019-04-22", "last_statement_issue_date": "2019-04-28", "last_statement_balance": 1708.77, "loan_name": "Consolidation", "loan_status": { "end_date": "2032-07-28", "type": "repayment" }, "minimum_payment_amount": 25, "next_payment_due_date": "2019-05-28", "origination_date": "2002-08-28", "origination_principal_amount": 25000, "outstanding_interest_amount": 6227.36, "payment_reference_number": "4277075694", "pslf_status": { "estimated_eligibility_date": "2021-01-01", "payments_made": 200, "payments_remaining": 160 }, "repayment_plan": { "description": "Standard Repayment", "type": "standard" }, "sequence_number": "1", "servicer_address": { "city": "San Matias", "country": "US", "postal_code": "99415", "region": "CA", "street": "123 Relaxation Road" }, "ytd_interest_paid": 280.55, "ytd_principal_paid": 271.65 } ] }, "request_id": "dTnnm60WgKGLnKL" } ``` ### Webhooks  Liabilities webhooks are sent to indicate that new loans or updated loan fields for existing accounts are available. \=\*=\*=\*= #### DEFAULT\_UPDATE  The webhook of type `LIABILITIES` and code `DEFAULT_UPDATE` will be fired when new or updated liabilities have been detected on a liabilities item. #### Properties  string `LIABILITIES` string `DEFAULT_UPDATE` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] An array of `account_id`'s for accounts that contain new liabilities.' object An object with keys of `account_id`'s that are mapped to their respective liabilities fields that changed. Example: `{ "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": ["past_amount_due"] }` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "LIABILITIES", "webhook_code": "DEFAULT_UPDATE", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "user_id": "usr_9nSp2KuZ2x4JDw", "error": null, "account_ids_with_new_liabilities": [ "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58", "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp" ], "account_ids_with_updated_liabilities": { "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": [ "past_amount_due" ] }, "environment": "production" } ``` --- # API - Monitor | Plaid Docs Monitor  ======== #### API reference for Monitor endpoints and webhooks  For how-to guidance, see the [Monitor documentation](https://plaid.com/docs/monitor/index.html.md) . | Endpoints | | | --- | --- | | [/watchlist\_screening/individual/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualcreate) | Create a watchlist screening for a person | | [/watchlist\_screening/individual/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualget) | Retrieve an individual watchlist screening | | [/watchlist\_screening/individual/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividuallist) | List individual watchlist screenings | | [/watchlist\_screening/individual/update](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualupdate) | Update individual watchlist screening | | [/watchlist\_screening/individual/history/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualhistorylist) | List history for entity watchlist screenings | | [/watchlist\_screening/individual/review/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualreviewcreate) | Create a review for an individual watchlist screening | | [/watchlist\_screening/individual/review/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualreviewlist) | List reviews for individual watchlist screenings | | [/watchlist\_screening/individual/hit/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualhitlist) | List hits for individual watchlist screenings | | [/watchlist\_screening/individual/program/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualprogramget) | Get individual watchlist screening programs | | [/watchlist\_screening/individual/program/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualprogramlist) | List individual watchlist screening programs | | [/watchlist\_screening/entity/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentitycreate) | Create a watchlist screening for an entity | | [/watchlist\_screening/entity/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityget) | Retrieve an individual watchlist screening | | [/watchlist\_screening/entity/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentitylist) | List individual watchlist screenings | | [/watchlist\_screening/entity/update](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityupdate) | Update individual watchlist screening | | [/watchlist\_screening/entity/history/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityhistorylist) | List history for individual watchlist screenings | | [/watchlist\_screening/entity/review/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityreviewcreate) | Create a review for an individual watchlist screening | | [/watchlist\_screening/entity/review/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityreviewlist) | List reviews for individual watchlist screenings | | [/watchlist\_screening/entity/hit/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityhitlist) | List hits for individual watchlist screenings | | [/watchlist\_screening/entity/program/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityprogramget) | Get individual watchlist screening programs | | [/watchlist\_screening/entity/program/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityprogramlist) | List individual watchlist screening programs | | See also | | | --- | --- | | [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) | Retrieve information about a dashboard user | | [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) | List dashboard users | | Webhooks | | | --- | --- | | [SCREENING: STATUS\_UPDATED](https://plaid.com/docs/api/products/monitor/index.html.md#screening-status_updated) | The status of an individual watchlist screening has changed | | [ENTITY\_SCREENING: STATUS\_UPDATED](https://plaid.com/docs/api/products/monitor/index.html.md#entity_screening-status_updated) | The status of an entity watchlist screening has changed | ### Endpoints  \=\*=\*=\*= #### /watchlist\_screening/individual/create  #### Create a watchlist screening for a person  Create a new Watchlist Screening to check your customer against watchlists defined in the associated Watchlist Program. If your associated program has ongoing screening enabled, this is the profile information that will be used to monitor your customer over time. #### Request fields  required, object Search inputs for creating a watchlist screening required, string ID of the associated program. required, string The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```node const request: WatchlistScreeningIndividualCreateRequest = { search_terms: { watchlist_program_id: 'prg_2eRPsDnL66rZ7H', legal_name: 'Aleksey Potemkin', date_of_birth: '1990-05-29', document_number: 'C31195855', country: 'US', }, client_user_id: 'example-client-user-id-123', }; try { const response = await client.watchlistScreeningIndividualCreate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/individual/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "search_terms": { "watchlist_program_id": "prg_2eRPsDnL66rZ7H", "legal_name": "Aleksey Potemkin", "date_of_birth": "1990-05-29", "document_number": "C31195855", "country": "US" }, "client_user_id": "example-client-user-id-123" }' ``` ```ruby request = Plaid::WatchlistScreeningIndividualCreateRequest.new( { search_terms: { watchlist_program_id: 'prg_2eRPsDnL66rZ7H', legal_name: 'Aleksey Potemkin', date_of_birth: '1990-05-29', document_number: 'C31195855', country: 'US', }, client_user_id: 'example-client-user-id-123', } ) response = client.watchlist_screening_individual_create(request) ``` ```java WatchlistScreeningRequestSearchTerms searchTerms = new WatchlistScreeningRequestSearchTerms() .watchlistProgramId("prg_2eRPsDnL66rZ7H") .legalName("Aleksey Potemkin") .dateOfBirth("1990-05-29") .documentNumber("C31195855") .country("US"); WatchlistScreeningIndividualCreateRequest request = new WatchlistScreeningIndividualCreateRequest() .searchTerms(searchTerms) .clientUserId("example-client-user-id-123"); Response response = client() .watchlistScreeningIndividualCreate(request) .execute(); ``` ```python request = WatchlistScreeningIndividualCreateRequest( search_terms=WatchlistScreeningRequestSearchTerms( watchlist_program_id='prg_2eRPsDnL66rZ7H', legal_name=WatchlistScreeningIndividualName('Aleksey Potemkin'), date_of_birth=datetime.date(1990, 1, 1), document_number=WatchlistScreeningDocumentValueNullable('C31195855'), country=GenericCountryCodeNullable('US'), ), client_user_id=ClientUserIDNullable('example-client-user-id-123'), ) response = client.watchlist_screening_individual_create(request) ``` ```go searchTerms := plaid.NewWatchlistScreeningRequestSearchTerms( "prg_2eRPsDnL66rZ7H", "Aleksey Potemkin", ) searchTerms.SetDateOfBirth("1990-05-29") searchTerms.SetDocumentNumber("C31195855") searchTerms.SetCountry("US") request := plaid.NewWatchlistScreeningIndividualCreateRequest(*searchTerms) request.SetClientUserId("example-client-user-id-123") response, _, err := client.PlaidApi. WatchlistScreeningIndividualCreate(ctx). WatchlistScreeningIndividualCreateRequest(*request). Execute() ``` #### Response fields  string ID of the associated screening. object Search terms for creating an individual watchlist screening string ID of the associated program. string The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. nullable, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. integer The current version of the search terms. Starts at `1` and increments with each edit to `search_terms`. nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` nullable, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "scr_52xR9LKo77r1Np", "search_terms": { "watchlist_program_id": "prg_2eRPsDnL66rZ7H", "legal_name": "Aleksey Potemkin", "date_of_birth": "1990-05-29", "document_number": "C31195855", "country": "US", "version": 1 }, "assignee": "54350110fedcbaf01234ffee", "status": "cleared", "client_user_id": "your-db-id-3b24110", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/individual/get  #### Retrieve an individual watchlist screening  Retrieve a previously created individual watchlist screening #### Request fields  required, string ID of the associated screening. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. ```node const request: WatchlistScreeningIndividualGetRequest = { watchlist_screening_id: 'scr_52xR9LKo77r1Np', }; try { const response = await client.watchlistScreeningIndividualGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/individual/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "watchlist_screening_id": "scr_52xR9LKo77r1Np" }' ``` ```ruby request = Plaid::WatchlistScreeningIndividualGetRequest.new( { watchlist_screening_id: "scr_52xR9LKo77r1Np" } ) response = client.watchlist_screening_individual_get(request) ``` ```java WatchlistScreeningIndividualGetRequest request = new WatchlistScreeningIndividualGetRequest() .watchlistScreeningId("scr_52xR9LKo77r1Np"); Response response = client() .watchlistScreeningIndividualGet(request) .execute(); ``` ```python request = WatchlistScreeningIndividualGetRequest( watchlist_screening_id='scr_52xR9LKo77r1Np', ) response = client.watchlist_screening_individual_get(request) ``` ```go request := plaid.NewWatchlistScreeningIndividualGetRequest("scr_52xR9LKo77r1Np") response, _, err := client.PlaidApi. WatchlistScreeningIndividualGet(ctx). WatchlistScreeningIndividualGetRequest(*request). Execute() ``` #### Response fields  string ID of the associated screening. object Search terms for creating an individual watchlist screening string ID of the associated program. string The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. nullable, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. integer The current version of the search terms. Starts at `1` and increments with each edit to `search_terms`. nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` nullable, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "scr_52xR9LKo77r1Np", "search_terms": { "watchlist_program_id": "prg_2eRPsDnL66rZ7H", "legal_name": "Aleksey Potemkin", "date_of_birth": "1990-05-29", "document_number": "C31195855", "country": "US", "version": 1 }, "assignee": "54350110fedcbaf01234ffee", "status": "cleared", "client_user_id": "your-db-id-3b24110", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/individual/list  #### List Individual Watchlist Screenings  List previously created watchlist screenings for individuals #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string ID of the associated program. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An identifier that determines which page of results you receive. ```node const request: WatchlistScreeningIndividualListRequest = { watchlist_program_id: 'prg_2eRPsDnL66rZ7H', client_user_id: 'example-client-user-id-123', }; try { const response = await client.watchlistScreeningIndividualList(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/individual/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "watchlist_program_id": "prg_2eRPsDnL66rZ7H", "client_user_id": "example-client-user-id-123" }' ``` ```ruby request = Plaid::WatchlistScreeningIndividualListRequest.new( { watchlist_program_id: 'prg_2eRPsDnL66rZ7H', client_user_id: 'example-client-user-id-123' } ) response = client.watchlist_screening_individual_list(request) ``` ```java WatchlistScreeningIndividualListRequest request = new WatchlistScreeningIndividualListRequest() .watchlistProgramId("prg_2eRPsDnL66rZ7H") .clientUserId("example-client-user-id-123"); Response response = client() .watchlistScreeningIndividualList(request) .execute(); ``` ```python request = WatchlistScreeningIndividualListRequest( watchlist_program_id='prg_2eRPsDnL66rZ7H', client_user_id=ClientUserIDNullable('example-client-user-id-123'), ) response = client.watchlist_screening_individual_list(request) ``` ```go request := plaid.NewWatchlistScreeningIndividualListRequest("prg_2eRPsDnL66rZ7H") response, _, err := client.PlaidApi. WatchlistScreeningIndividualList(ctx). WatchlistScreeningIndividualListRequest(*request). Execute() ``` #### Response fields  \[object\] List of individual watchlist screenings string ID of the associated screening. object Search terms for creating an individual watchlist screening string ID of the associated program. string The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. nullable, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. integer The current version of the search terms. Starts at `1` and increments with each edit to `search_terms`. nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` nullable, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "watchlist_screenings": [ { "id": "scr_52xR9LKo77r1Np", "search_terms": { "watchlist_program_id": "prg_2eRPsDnL66rZ7H", "legal_name": "Aleksey Potemkin", "date_of_birth": "1990-05-29", "document_number": "C31195855", "country": "US", "version": 1 }, "assignee": "54350110fedcbaf01234ffee", "status": "cleared", "client_user_id": "your-db-id-3b24110", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/individual/update  #### Update individual watchlist screening  Update a specific individual watchlist screening. This endpoint can be used to add additional customer information, correct outdated information, add a reference id, assign the individual to a reviewer, and update which program it is associated with. Please note that you may not update `search_terms` and `status` at the same time since editing `search_terms` may trigger an automatic `status` change. #### Request fields  required, string ID of the associated screening. object Search terms for editing an individual watchlist screening string ID of the associated program. string The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. \[string\] A list of fields to reset back to null Possible values: `assignee` ```node const request: WatchlistScreeningIndividualUpdateRequest = { watchlist_screening_id: 'scr_52xR9LKo77r1Np', status: 'cleared', }; try { const response = await client.watchlistScreeningIndividualUpdate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/individual/update \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "watchlist_screening_id": "scr_52xR9LKo77r1Np", "status": "cleared" }' ``` ```ruby request = Plaid::WatchlistScreeningIndividualUpdateRequest.new( { watchlist_screening_id: 'scr_52xR9LKo77r1Np', status: 'cleared' } ) response = client.watchlist_screening_individual_update(request) ``` ```java WatchlistScreeningIndividualUpdateRequest request = new WatchlistScreeningIndividualUpdateRequest() .watchlistScreeningId("scr_52xR9LKo77r1Np") .status("cleared"); Response response = client() .watchlistScreeningIndividualUpdate(request) .execute(); ``` ```python request = WatchlistScreeningIndividualUpdateRequest( watchlist_screening_id='scr_52xR9LKo77r1Np', status=WatchlistScreeningStatusNullable('cleared'), ) response = client.watchlist_screening_individual_update(request) ``` ```go request := plaid.NewWatchlistScreeningIndividualUpdateRequest("scr_52xR9LKo77r1Np") request.SetStatus("cleared") response, _, err := client.PlaidApi. WatchlistScreeningIndividualUpdate(ctx). WatchlistScreeningIndividualUpdateRequest(*request). Execute() ``` #### Response fields  string ID of the associated screening. object Search terms for creating an individual watchlist screening string ID of the associated program. string The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. nullable, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. integer The current version of the search terms. Starts at `1` and increments with each edit to `search_terms`. nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` nullable, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "scr_52xR9LKo77r1Np", "search_terms": { "watchlist_program_id": "prg_2eRPsDnL66rZ7H", "legal_name": "Aleksey Potemkin", "date_of_birth": "1990-05-29", "document_number": "C31195855", "country": "US", "version": 1 }, "assignee": "54350110fedcbaf01234ffee", "status": "cleared", "client_user_id": "your-db-id-3b24110", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/individual/history/list  #### List history for individual watchlist screenings  List all changes to the individual watchlist screening in reverse-chronological order. If the watchlist screening has not been edited, no history will be returned. #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string ID of the associated screening. string An identifier that determines which page of results you receive. ```node const request: WatchlistScreeningIndividualHistoryListRequest = { watchlist_screening_id: 'scr_52xR9LKo77r1Np', }; try { const response = await client.watchlistScreeningIndividualHistoryList( request, ); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/individual/history/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "watchlist_screening_id": "scr_52xR9LKo77r1Np" }' ``` ```ruby request = Plaid::WatchlistScreeningIndividualHistoryListRequest.new( { watchlist_screening_id: 'scr_52xR9LKo77r1Np' } ) response = client.watchlist_screening_individual_history_list(request) ``` ```java WatchlistScreeningIndividualHistoryListRequest request = new WatchlistScreeningIndividualHistoryListRequest() .watchlistScreeningId("scr_52xR9LKo77r1Np"); Response response = client() .watchlistScreeningIndividualHistoryList(request) .execute(); ``` ```python request = WatchlistScreeningIndividualHistoryListRequest( watchlist_screening_id='scr_52xR9LKo77r1Np' ) response = client.watchlist_screening_individual_history_list(request) ``` ```go request := plaid.NewWatchlistScreeningIndividualHistoryListRequest("scr_52xR9LKo77r1Np") response, _, err := client.PlaidApi. WatchlistScreeningIndividualHistoryList(ctx). WatchlistScreeningIndividualHistoryListRequest(*request). Execute() ``` #### Response fields  \[object\] List of individual watchlist screenings string ID of the associated screening. object Search terms for creating an individual watchlist screening string ID of the associated program. string The legal name of the individual being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. nullable, string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` nullable, string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. nullable, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. integer The current version of the search terms. Starts at `1` and increments with each edit to `search_terms`. nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` nullable, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "watchlist_screenings": [ { "id": "scr_52xR9LKo77r1Np", "search_terms": { "watchlist_program_id": "prg_2eRPsDnL66rZ7H", "legal_name": "Aleksey Potemkin", "date_of_birth": "1990-05-29", "document_number": "C31195855", "country": "US", "version": 1 }, "assignee": "54350110fedcbaf01234ffee", "status": "cleared", "client_user_id": "your-db-id-3b24110", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/individual/review/create  #### Create a review for an individual watchlist screening  Create a review for the individual watchlist screening. Reviews are compliance reports created by users in your organization regarding the relevance of potential hits found by Plaid. #### Request fields  required, \[string\] Hits to mark as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected. required, \[string\] Hits to mark as a false positive after thorough manual review. These hits will never recur or be updated once dismissed. string A comment submitted by a team member as part of reviewing a watchlist screening. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string ID of the associated screening. ```node const request: WatchlistScreeningIndividualReviewCreateRequest = { confirmed_hits: ['scrhit_52xR9LKo77r1Np'], dismissed_hits: [], watchlist_screening_id: 'scr_52xR9LKo77r1Np', }; try { const response = await client.watchlistScreeningIndividualReviewCreate( request, ); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/individual/review/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "confirmed_hits": [ "scrhit_52xR9LKo77r1Np" ], "dismissed_hits": [], "watchlist_screening_id": "scr_52xR9LKo77r1Np" }' ``` ```ruby request = Plaid::WatchlistScreeningIndividualReviewCreateRequest.new( { confirmed_hits: ['scrhit_52xR9LKo77r1Np'], dismissed_hits: [], watchlist_screening_id: "scr_52xR9LKo77r1Np", } ) response = client.watchlist_screening_individual_review_create(request) ``` ```java List confirmedHits = new ArrayList(); confirmedHits.add("scr_52xR9LKo77r1Np"); List dismissedHits = new ArrayList(); WatchlistScreeningIndividualReviewCreateRequest request = new WatchlistScreeningIndividualReviewCreateRequest() .confirmedHits(confirmedHits) .dismissedHits(dismissedHits) .watchlistScreeningId("scr_52xR9LKo77r1Np"); Response response = client() .watchlistScreeningIndividualReviewCreate(request) .execute(); ``` ```python request = WatchlistScreeningIndividualReviewCreateRequest( confirmed_hits=['scrhit_52xR9LKo77r1Np'], dismissed_hits=[], watchlist_screening_id="scr_52xR9LKo77r1Np", ) response = client.watchlist_screening_individual_review_create(request) ``` ```go request := plaid.NewWatchlistScreeningIndividualReviewCreateRequest( []string{"scrhit_52xR9LKo77r1Np"}, []string{}, "scr_52xR9LKo77r1Np", ) response, _, err := client.PlaidApi. WatchlistScreeningIndividualReviewCreate(ctx). WatchlistScreeningIndividualReviewCreateRequest(*request). Execute() ``` #### Response fields  string ID of the associated review. \[string\] Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected. \[string\] Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed. nullable, string A comment submitted by a team member as part of reviewing a watchlist screening. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "rev_aCLNRxK3UVzn2r", "confirmed_hits": [ "scrhit_52xR9LKo77r1Np" ], "dismissed_hits": [ "scrhit_52xR9LKo77r1Np" ], "comment": "These look like legitimate matches, rejecting the customer.", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/individual/review/list  #### List reviews for individual watchlist screenings  List all reviews for the individual watchlist screening. #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string ID of the associated screening. string An identifier that determines which page of results you receive. ```node const request: WatchlistScreeningIndividualReviewListRequest = { watchlist_screening_id: 'scr_52xR9LKo77r1Np', }; try { const response = await client.watchlistScreeningIndividualReviewList(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/individual/review/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "watchlist_screening_id": "scr_52xR9LKo77r1Np" }' ``` ```ruby request = Plaid::WatchlistScreeningIndividualReviewListRequest.new( { watchlist_screening_id: 'scr_52xR9LKo77r1Np' } ) response = client.watchlist_screening_individual_review_list(request) ``` ```java WatchlistScreeningIndividualReviewListRequest request = new WatchlistScreeningIndividualReviewListRequest() .watchlistScreeningId("scr_52xR9LKo77r1Np"); Response response = client() .watchlistScreeningIndividualReviewList(request) .execute(); ``` ```python request = WatchlistScreeningIndividualReviewListRequest( watchlist_screening_id='scr_52xR9LKo77r1Np', ) response = client.watchlist_screening_individual_review_list(request) ``` ```go request := plaid.NewWatchlistScreeningIndividualReviewListRequest("scr_52xR9LKo77r1Np") response, _, err := client.PlaidApi. WatchlistScreeningIndividualReviewList(ctx). WatchlistScreeningIndividualReviewListRequest(*request). Execute() ``` #### Response fields  \[object\] List of screening reviews string ID of the associated review. \[string\] Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected. \[string\] Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed. nullable, string A comment submitted by a team member as part of reviewing a watchlist screening. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "watchlist_screening_reviews": [ { "id": "rev_aCLNRxK3UVzn2r", "confirmed_hits": [ "scrhit_52xR9LKo77r1Np" ], "dismissed_hits": [ "scrhit_52xR9LKo77r1Np" ], "comment": "These look like legitimate matches, rejecting the customer.", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/individual/hit/list  #### List hits for individual watchlist screening  List all hits found by Plaid for a particular individual watchlist screening. #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string ID of the associated screening. string An identifier that determines which page of results you receive. ```node const request: WatchlistScreeningIndividualHitListRequest = { watchlist_screening_id: 'scr_52xR9LKo77r1Np', }; try { const response = await client.watchlistScreeningIndividualHitList(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/individual/hit/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "watchlist_screening_id": "scr_52xR9LKo77r1Np" }' ``` ```ruby request = Plaid::WatchlistScreeningIndividualHitListRequest.new( { watchlist_screening_id: 'scr_52xR9LKo77r1Np' } ) response = client.watchlist_screening_individual_hit_list(request) ``` ```java WatchlistScreeningIndividualHitListRequest request = new WatchlistScreeningIndividualHitListRequest() .watchlistScreeningId("scr_52xR9LKo77r1Np"); Response response = client() .watchlistScreeningIndividualHitList(request) .execute(); ``` ```python request = WatchlistScreeningIndividualHitListRequest( watchlist_screening_id='scr_52xR9LKo77r1Np', ) response = client.watchlist_screening_individual_hit_list(request) ``` ```go request := plaid.NewWatchlistScreeningIndividualHitListRequest("scr_52xR9LKo77r1Np") response, _, err := client.PlaidApi. WatchlistScreeningIndividualHitList(ctx). WatchlistScreeningIndividualHitListRequest(*request). Execute() ``` #### Response fields  \[object\] List of individual watchlist screening hits string ID of the associated screening hit. string The current state of review. All watchlist screening hits begin in a `pending_review` state but can be changed by creating a review. When a hit is in the `pending_review` state, it will always show the latest version of the watchlist data Plaid has available and be compared against the latest customer information saved in the watchlist screening. Once a hit has been marked as `confirmed` or `dismissed` it will no longer be updated so that the state is as it was when the review was first conducted. Possible values: `confirmed`, `pending_review`, `dismissed` string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` string Shorthand identifier for a specific screening list for individuals. `AU_CON`: Australia Department of Foreign Affairs and Trade Consolidated List `CA_CON`: Government of Canada Consolidated List of Sanctions `EU_CON`: European External Action Service Consolidated List `IZ_CIA`: CIA List of Chiefs of State and Cabinet Members `IZ_IPL`: Interpol Red Notices for Wanted Persons List `IZ_PEP`: Politically Exposed Persons List `IZ_UNC`: United Nations Consolidated Sanctions `IZ_WBK`: World Bank Listing of Ineligible Firms and Individuals `UK_HMC`: UK HM Treasury Consolidated List `US_DPL`: Bureau of Industry and Security Denied Persons List `US_DTC`: US Department of State AECA Debarred `US_FBI`: US Department of Justice FBI Wanted List `US_FSE`: US OFAC Foreign Sanctions Evaders `US_ISN`: US Department of State Nonproliferation Sanctions `US_PLC`: US OFAC Palestinian Legislative Council `US_SAM`: US System for Award Management Exclusion List `US_SDN`: US OFAC Specially Designated Nationals List `US_SSI`: US OFAC Sectoral Sanctions Identifications `SG_SOF`: Government of Singapore Terrorists and Terrorist Entities `TR_TWL`: Government of Turkey Terrorist Wanted List `TR_DFD`: Government of Turkey Domestic Freezing Decisions `TR_FOR`: Government of Turkey Foreign Freezing Requests `TR_WMD`: Government of Turkey Weapons of Mass Destruction `TR_CMB`: Government of Turkey Capital Markets Board Possible values: `AU_CON`, `CA_CON`, `EU_CON`, `IZ_CIA`, `IZ_IPL`, `IZ_PEP`, `IZ_UNC`, `IZ_WBK`, `UK_HMC`, `US_DPL`, `US_DTC`, `US_FBI`, `US_FSE`, `US_ISN`, `US_MBS`, `US_PLC`, `US_SAM`, `US_SDN`, `US_SSI`, `SG_SOF`, `TR_TWL`, `TR_DFD`, `TR_FOR`, `TR_WMD`, `TR_CMB` string A universal identifier for a watchlist individual that is stable across searches and updates. nullable, string The identifier provided by the source sanction or watchlist. When one is not provided by the source, this is `null`. object Analysis information describing why a screening hit matched the provided user information string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` integer The version of the screening's `search_terms` that were compared when the screening hit was added. screening hits are immutable once they have been reviewed. If changes are detected due to updates to the screening's `search_terms`, the associated program, or the list's source data prior to review, the screening hit will be updated to reflect those changes. object Information associated with the watchlist hit \[object\] Dates of birth associated with the watchlist hit object Summary object reflecting the match result of the associated data string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object A date range with a start and end date string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` string A date in the format YYYY-MM-DD (RFC 3339 Section 5.6). Format: `date` \[object\] Documents associated with the watchlist hit object Summary object reflecting the match result of the associated data string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object An official document, usually issued by a governing body or institution, with an associated identifier. string The kind of official document represented by this object. `birth_certificate` - A certificate of birth `drivers_license` - A license to operate a motor vehicle `immigration_number` - Immigration or residence documents `military_id` - Identification issued by a military group `other` - Any document not covered by other categories `passport` - An official passport issue by a government `personal_identification` - Any generic personal identification that is not covered by other categories `ration_card` - Identification that entitles the holder to rations `ssn` - United States Social Security Number `student_id` - Identification issued by an educational institution `tax_id` - Identification issued for the purpose of collecting taxes `travel_document` - Visas, entry permits, refugee documents, etc. `voter_id` - Identification issued for the purpose of voting Possible values: `birth_certificate`, `drivers_license`, `immigration_number`, `military_id`, `other`, `passport`, `personal_identification`, `ration_card`, `ssn`, `student_id`, `tax_id`, `travel_document`, `voter_id` string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. \[object\] Locations associated with the watchlist hit object Summary object reflecting the match result of the associated data string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Location information for the associated individual watchlist hit string The full location string, potentially including elements like street, city, postal codes and country codes. Note that this is not necessarily a complete or well-formatted address. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. \[object\] Names associated with the watchlist hit object Summary object reflecting the match result of the associated data string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Name information for the associated individual watchlist hit string The full name of the individual, including all parts. boolean Primary names are those most commonly used to refer to this person. Only one name will ever be marked as primary. string Names that are explicitly marked as low quality either by their `source` list, or by `plaid` by a series of additional checks done by Plaid. Plaid does not ever surface a hit as a result of a weak name alone. If a name has no quality issues, this value will be `none`. Possible values: `none`, `source`, `plaid` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "watchlist_screening_hits": [ { "id": "scrhit_52xR9LKo77r1Np", "review_status": "pending_review", "first_active": "2020-07-24T03:26:02Z", "inactive_since": "2020-07-24T03:26:02Z", "historical_since": "2020-07-24T03:26:02Z", "list_code": "US_SDN", "plaid_uid": "uid_3NggckTimGSJHS", "source_uid": "26192ABC", "analysis": { "dates_of_birth": "match", "documents": "match", "locations": "match", "names": "match", "search_terms_version": 1 }, "data": { "dates_of_birth": [ { "analysis": { "summary": "match" }, "data": { "beginning": "1990-05-29", "ending": "1990-05-29" } } ], "documents": [ { "analysis": { "summary": "match" }, "data": { "type": "passport", "number": "C31195855" } } ], "locations": [ { "analysis": { "summary": "match" }, "data": { "full": "Florida, US", "country": "US" } } ], "names": [ { "analysis": { "summary": "match" }, "data": { "full": "Aleksey Potemkin", "is_primary": false, "weak_alias_determination": "none" } } ] } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/individual/program/get  #### Get individual watchlist screening program  Get an individual watchlist screening program #### Request fields  required, string ID of the associated program. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. ```node const request: WatchlistScreeningIndividualProgramGetRequest = { watchlist_program_id: 'prg_2eRPsDnL66rZ7H', }; try { const response = await client.watchlistScreeningIndividualProgramGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/individual/program/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "watchlist_program_id": "prg_2eRPsDnL66rZ7H" }' ``` ```ruby request = Plaid::WatchlistScreeningIndividualProgramGetRequest.new( { watchlist_program_id: 'prg_2eRPsDnL66rZ7H' } ) response = client.watchlist_screening_individual_program_get(request) ``` ```java WatchlistScreeningIndividualProgramGetRequest request = new WatchlistScreeningIndividualProgramGetRequest() .watchlistProgramId("prg_2eRPsDnL66rZ7H"); Response response = client() .watchlistScreeningIndividualProgramGet(request) .execute(); ``` ```python request = WatchlistScreeningIndividualProgramGetRequest( watchlist_program_id='prg_2eRPsDnL66rZ7H', ) response = client.watchlist_screening_individual_program_get(request) ``` ```go request := plaid.NewWatchlistScreeningIndividualProgramGetRequest("prg_2eRPsDnL66rZ7H") response, _, err := client.PlaidApi. WatchlistScreeningIndividualProgramGet(ctx). WatchlistScreeningIndividualProgramGetRequest(*request). Execute() ``` #### Response fields  string ID of the associated program. string An ISO8601 formatted timestamp. Format: `date-time` boolean Indicator specifying whether the program is enabled and will perform daily rescans. \[string\] Watchlists enabled for the associated program Possible values: `AU_CON`, `CA_CON`, `EU_CON`, `IZ_CIA`, `IZ_IPL`, `IZ_PEP`, `IZ_UNC`, `IZ_WBK`, `UK_HMC`, `US_DPL`, `US_DTC`, `US_FBI`, `US_FSE`, `US_ISN`, `US_MBS`, `US_PLC`, `US_SAM`, `US_SDN`, `US_SSI`, `SG_SOF`, `TR_TWL`, `TR_DFD`, `TR_FOR`, `TR_WMD`, `TR_CMB` string A name for the program to define its purpose. For example, "High Risk Individuals", "US Cardholders", or "Applicants". string The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity. `coarse` - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review. `balanced` - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise. `strict` - Aggressive false positive reduction. This sensitivity will require names to be more similar than `coarse` and `balanced` settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations. `exact` - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case. Possible values: `coarse`, `balanced`, `strict`, `exact` object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` boolean Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "prg_2eRPsDnL66rZ7H", "created_at": "2020-07-24T03:26:02Z", "is_rescanning_enabled": true, "lists_enabled": [ "US_SDN" ], "name": "Sample Program", "name_sensitivity": "balanced", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "is_archived": false, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/individual/program/list  #### List individual watchlist screening programs  List all individual watchlist screening programs #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string An identifier that determines which page of results you receive. ```node try { const response = await client.watchlistScreeningIndividualProgramList({}); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/individual/program/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}" }' ``` ```ruby response = client.watchlist_screening_individual_program_list({}) ``` ```java Response response = client() .watchlistScreeningIndividualProgramList(new Object()) .execute(); ``` ```python request = WatchlistScreeningIndividualProgramListRequest( cursor='eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM' ) response = client.watchlist_screening_individual_program_list(request) ``` ```go request := plaid.NewWatchlistScreeningIndividualProgramListRequest() response, _, err := client.PlaidApi. WatchlistScreeningIndividualProgramList(ctx). WatchlistScreeningIndividualProgramListRequest(*request). Execute() ``` #### Response fields  \[object\] List of individual watchlist screening programs string ID of the associated program. string An ISO8601 formatted timestamp. Format: `date-time` boolean Indicator specifying whether the program is enabled and will perform daily rescans. \[string\] Watchlists enabled for the associated program Possible values: `AU_CON`, `CA_CON`, `EU_CON`, `IZ_CIA`, `IZ_IPL`, `IZ_PEP`, `IZ_UNC`, `IZ_WBK`, `UK_HMC`, `US_DPL`, `US_DTC`, `US_FBI`, `US_FSE`, `US_ISN`, `US_MBS`, `US_PLC`, `US_SAM`, `US_SDN`, `US_SSI`, `SG_SOF`, `TR_TWL`, `TR_DFD`, `TR_FOR`, `TR_WMD`, `TR_CMB` string A name for the program to define its purpose. For example, "High Risk Individuals", "US Cardholders", or "Applicants". string The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity. `coarse` - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review. `balanced` - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise. `strict` - Aggressive false positive reduction. This sensitivity will require names to be more similar than `coarse` and `balanced` settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations. `exact` - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case. Possible values: `coarse`, `balanced`, `strict`, `exact` object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` boolean Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring. nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "watchlist_programs": [ { "id": "prg_2eRPsDnL66rZ7H", "created_at": "2020-07-24T03:26:02Z", "is_rescanning_enabled": true, "lists_enabled": [ "US_SDN" ], "name": "Sample Program", "name_sensitivity": "balanced", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "is_archived": false } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/entity/create  #### Create a watchlist screening for an entity  Create a new entity watchlist screening to check your customer against watchlists defined in the associated entity watchlist program. If your associated program has ongoing screening enabled, this is the profile information that will be used to monitor your customer over time. #### Request fields  required, object Search inputs for creating an entity watchlist screening required, string ID of the associated entity program. required, string The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. string A phone number in E.164 format. string An 'http' or 'https' URL (must begin with either of those). Format: `uri` string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```node const request: WatchlistScreeningEntityCreateRequest = { search_terms: { entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H', legal_name: 'Example Screening Entity', document_number: 'C31195855', email_address: 'user@example.com', country: 'US', phone_number: '+14025671234', url: 'https://example.com', }, client_user_id: 'example-client-user-id-123', }; try { const response = await client.watchlistScreeningEntityCreate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/entity/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "search_terms": { "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H", "legal_name": "Example Screening Entity", "document_number": "C31195855", "email_address": "user@example.com", "country": "US", "phone_number": "+14025671234", "url": "https://example.com" }, "client_user_id": "example-client-user-id-123" }' ``` ```ruby request = Plaid::WatchlistScreeningEntityCreateRequest.new( { search_terms: { entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H', legal_name: 'Example Screening Entity', document_number: 'C31195855', email_address: 'user@example.com', country: 'US', phone_number: '+14025671234', url: 'https://example.com', }, client_user_id: 'example-client-user-id-123', } ) response = client.watchlist_screening_entity_create(request) ``` ```java EntityWatchlistScreeningSearchTerms searchTerms = new EntityWatchlistScreeningSearchTerms() .entityWatchlistProgramId("entprg_2eRPsDnL66rZ7H") .legalName("Example Screening Entity") .emailAddress("user@example.com") .documentNumber("C31195855") .country("US") .phoneNumber("+14025671234") .url("https://example.com"); WatchlistScreeningEntityCreateRequest request = new WatchlistScreeningEntityCreateRequest() .searchTerms(searchTerms) .clientUserId("example-client-user-id-123"); Response response = client() .watchlistScreeningEntityCreate(request) .execute(); ``` ```python request = WatchlistScreeningEntityCreateRequest( search_terms=EntityWatchlistSearchTerms( entity_watchlist_program_id='entprg_2eRPsDnL66rZ7H', legal_name=EntityWatchlistScreeningName('Example Screening Entity'), document_number=WatchlistScreeningDocumentValueNullable('C31195855'), email_address='user@example.com', country=GenericCountryCodeNullable('US'), phone_number=WatchlistScreeningPhoneNumberNullable('+14025671234'), url='https://example.com', ), client_user_id=ClientUserIDNullable('example-client-user-id-123') ) response = client.watchlist_screening_entity_create(request) ``` ```go searchTerms := plaid.NewEntityWatchlistSearchTerms( "entprg_2eRPsDnL66rZ7H", "Example Screening Entity", ) searchTerms.SetEmailAddress("user@example.com") searchTerms.SetPhoneNumber("14025671234") searchTerms.SetDocumentNumber("C31195855") searchTerms.SetUrl("https://example.com") searchTerms.SetCountry("US") request := plaid.NewWatchlistScreeningEntityCreateRequest(*searchTerms) request.SetClientUserId("example-client-user-id-123") response, _, err := client.PlaidApi. WatchlistScreeningEntityCreate(ctx). WatchlistScreeningEntityCreateRequest(*request). Execute() ``` #### Response fields  string ID of the associated entity screening. object Search terms associated with an entity used for searching against watchlists string ID of the associated entity program. string The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. nullable, string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A phone number in E.164 format. nullable, string An 'http' or 'https' URL (must begin with either of those). Format: `uri` integer The current version of the search terms. Starts at `1` and increments with each edit to `search_terms`. nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` nullable, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "entscr_52xR9LKo77r1Np", "search_terms": { "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H", "legal_name": "Al-Qaida", "document_number": "C31195855", "email_address": "user@example.com", "country": "US", "phone_number": "+14025671234", "url": "https://example.com", "version": 1 }, "assignee": "54350110fedcbaf01234ffee", "status": "cleared", "client_user_id": "your-db-id-3b24110", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/entity/get  #### Get an entity screening  Retrieve an entity watchlist screening. #### Request fields  required, string ID of the associated entity screening. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. ```node const request: WatchlistScreeningEntityGetRequest = { entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np', }; try { const response = await client.watchlistScreeningEntityGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/entity/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "entity_watchlist_screening_id": "entscr_52xR9LKo77r1Np" }' ``` ```ruby request = Plaid::WatchlistScreeningEntityGetRequest.new( { entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np' } ) response = client.watchlist_screening_entity_get(request) ``` ```java WatchlistScreeningEntityGetRequest request = new WatchlistScreeningEntityGetRequest() .entityWatchlistScreeningId("entscr_52xR9LKo77r1Np"); Response response = client() .watchlistScreeningEntityGet(request) .execute(); ``` ```python request = WatchlistScreeningEntityGetRequest( entity_watchlist_screening_id='entscr_52xR9LKo77r1Np', ) response = client.watchlist_screening_entity_get(request) ``` ```go request := plaid.NewWatchlistScreeningEntityGetRequest("entscr_52xR9LKo77r1Np") response, _, err := client.PlaidApi. WatchlistScreeningEntityGet(ctx). WatchlistScreeningEntityGetRequest(*request). Execute() ``` #### Response fields  string ID of the associated entity screening. object Search terms associated with an entity used for searching against watchlists string ID of the associated entity program. string The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. nullable, string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A phone number in E.164 format. nullable, string An 'http' or 'https' URL (must begin with either of those). Format: `uri` integer The current version of the search terms. Starts at `1` and increments with each edit to `search_terms`. nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` nullable, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "entscr_52xR9LKo77r1Np", "search_terms": { "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H", "legal_name": "Al-Qaida", "document_number": "C31195855", "email_address": "user@example.com", "country": "US", "phone_number": "+14025671234", "url": "https://example.com", "version": 1 }, "assignee": "54350110fedcbaf01234ffee", "status": "cleared", "client_user_id": "your-db-id-3b24110", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/entity/list  #### List entity watchlist screenings  List all entity screenings. #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string ID of the associated entity program. string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An identifier that determines which page of results you receive. ```node const request: WatchlistScreeningEntityListRequest = { entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H', }; try { const response = await client.watchlistScreeningEntityList(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/entity/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H" }' ``` ```ruby request = Plaid::WatchlistScreeningEntityListRequest.new( { entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H' } ) response = client.watchlist_screening_entity_list(request) ``` ```java WatchlistScreeningEntityListRequest request = new WatchlistScreeningEntityListRequest() .entityWatchlistProgramId("entprg_2eRPsDnL66rZ7H"); Response response = client() .watchlistScreeningEntityList(request) .execute(); ``` ```python request = WatchlistScreeningEntityListRequest( entity_watchlist_program_id='entprg_2eRPsDnL66rZ7H' ) response = client.watchlist_screening_entity_list(request) ``` ```go request := plaid.NewWatchlistScreeningEntityListRequest("entprg_2eRPsDnL66rZ7H") response, _, err := client.PlaidApi. WatchlistScreeningEntityList(ctx). WatchlistScreeningEntityListRequest(*request). Execute() ``` #### Response fields  \[object\] List of entity watchlist screening string ID of the associated entity screening. object Search terms associated with an entity used for searching against watchlists string ID of the associated entity program. string The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. nullable, string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A phone number in E.164 format. nullable, string An 'http' or 'https' URL (must begin with either of those). Format: `uri` integer The current version of the search terms. Starts at `1` and increments with each edit to `search_terms`. nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` nullable, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "entity_watchlist_screenings": [ { "id": "entscr_52xR9LKo77r1Np", "search_terms": { "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H", "legal_name": "Al-Qaida", "document_number": "C31195855", "email_address": "user@example.com", "country": "US", "phone_number": "+14025671234", "url": "https://example.com", "version": 1 }, "assignee": "54350110fedcbaf01234ffee", "status": "cleared", "client_user_id": "your-db-id-3b24110", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/entity/update  #### Update an entity screening  Update an entity watchlist screening. #### Request fields  required, string ID of the associated entity screening. object Search terms for editing an entity watchlist screening required, string ID of the associated entity program. string The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. string A phone number in E.164 format. string An 'http' or 'https' URL (must begin with either of those). Format: `uri` string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. \[string\] A list of fields to reset back to null Possible values: `assignee` ```node const request: WatchlistScreeningEntityUpdateRequest = { entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np', status: 'cleared', }; try { const response = await client.watchlistScreeningEntityUpdate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/entity/update \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "entity_watchlist_screening_id": "entscr_52xR9LKo77r1Np", "status": "cleared" }' ``` ```ruby request = Plaid::WatchlistScreeningEntityUpdateRequest.new( { entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np', status: 'cleared' } ) response = client.watchlist_entity_screening_update(request) ``` ```java WatchlistScreeningEntityUpdateRequest request = new WatchlistScreeningEntityUpdateRequest() .entityWatchlistScreeningId("entscr_52xR9LKo77r1Np") .status("cleared"); Response response = client() .watchlistScreeningEntityUpdate(request) .execute(); ``` ```python request = WatchlistScreeningEntityUpdateRequest( entity_watchlist_screening_id='entscr_52xR9LKo77r1Np', status=WatchlistScreeningStatusNullable('cleared'), ) response = client.watchlist_entity_screening_update(request) ``` ```go request := plaid.NewWatchlistScreeningEntityUpdateRequest("entscr_52xR9LKo77r1Np") request.SetStatus(plaid.WATCHLISTSCREENINGSTATUS_CLEARED) response, _, err := client.PlaidApi. WatchlistScreeningEntityUpdate(ctx). WatchlistScreeningEntityUpdateRequest(*request). Execute() ``` #### Response fields  string ID of the associated entity screening. object Search terms associated with an entity used for searching against watchlists string ID of the associated entity program. string The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. nullable, string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A phone number in E.164 format. nullable, string An 'http' or 'https' URL (must begin with either of those). Format: `uri` integer The current version of the search terms. Starts at `1` and increments with each edit to `search_terms`. nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` nullable, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "entscr_52xR9LKo77r1Np", "search_terms": { "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H", "legal_name": "Al-Qaida", "document_number": "C31195855", "email_address": "user@example.com", "country": "US", "phone_number": "+14025671234", "url": "https://example.com", "version": 1 }, "assignee": "54350110fedcbaf01234ffee", "status": "cleared", "client_user_id": "your-db-id-3b24110", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/entity/history/list  #### List history for entity watchlist screenings  List all changes to the entity watchlist screening in reverse-chronological order. If the watchlist screening has not been edited, no history will be returned. #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string ID of the associated entity screening. string An identifier that determines which page of results you receive. ```node const request: WatchlistScreeningEntityHistoryListRequest = { entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np', }; try { const response = await client.watchlistScreeningEntityHistoryList(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/entity/history/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "entity_watchlist_screening_id": "entscr_52xR9LKo77r1Np" }' ``` ```ruby request = Plaid::WatchlistScreeningEntityHistoryListRequest.new( { entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np' } ) response = client.watchlist_screening_entity_history_list(request) ``` ```java WatchlistScreeningEntityHistoryListRequest request = new WatchlistScreeningEntityHistoryListRequest() .entityWatchlistScreeningId("entscr_52xR9LKo77r1Np"); Response response = client() .watchlistScreeningEntityHistoryList(request) .execute(); ``` ```python request = WatchlistScreeningEntityHistoryListRequest( entity_watchlist_screening_id='entscr_52xR9LKo77r1Np', ) response = client.watchlist_screening_entity_history_list(request) ``` ```go request := plaid.NewWatchlistScreeningEntityHistoryListRequest("entscr_52xR9LKo77r1Np") response, _, err := client.PlaidApi. WatchlistScreeningEntityHistoryList(ctx). WatchlistScreeningEntityHistoryListRequest(*request). Execute() ``` #### Response fields  \[object\] List of entity watchlist screening string ID of the associated entity screening. object Search terms associated with an entity used for searching against watchlists string ID of the associated entity program. string The name of the organization being screened. Must have at least one alphabetical character, have a maximum length of 100 characters, and not include leading or trailing spaces. nullable, string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. nullable, string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` nullable, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. nullable, string A phone number in E.164 format. nullable, string An 'http' or 'https' URL (must begin with either of those). Format: `uri` integer The current version of the search terms. Starts at `1` and increments with each edit to `search_terms`. nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string A status enum indicating whether a screening is still pending review, has been rejected, or has been cleared. Possible values: `rejected`, `pending_review`, `cleared` nullable, string A unique ID that identifies the end user in your system. Either a `user_id` or the `client_user_id` must be provided. This ID can also be used to associate user-specific data from other Plaid products. Financial Account Matching requires this field and the `/link/token/create` `client_user_id` to be consistent. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "entity_watchlist_screenings": [ { "id": "entscr_52xR9LKo77r1Np", "search_terms": { "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H", "legal_name": "Al-Qaida", "document_number": "C31195855", "email_address": "user@example.com", "country": "US", "phone_number": "+14025671234", "url": "https://example.com", "version": 1 }, "assignee": "54350110fedcbaf01234ffee", "status": "cleared", "client_user_id": "your-db-id-3b24110", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/entity/review/create  #### Create a review for an entity watchlist screening  Create a review for an entity watchlist screening. Reviews are compliance reports created by users in your organization regarding the relevance of potential hits found by Plaid. #### Request fields  required, \[string\] Hits to mark as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected. required, \[string\] Hits to mark as a false positive after thorough manual review. These hits will never recur or be updated once dismissed. string A comment submitted by a team member as part of reviewing a watchlist screening. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string ID of the associated entity screening. ```node const request: WatchlistScreeningEntityReviewCreateRequest = { entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np', }; try { const response = await client.watchlistScreeningEntityReviewCreate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/entity/review/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "confirmed_hits": [ "entscrhit_52xR9LKo77r1Np" ], "dismissed_hits": [], "entity_watchlist_screening_id": "entscr_52xR9LKo77r1Np" }' ``` ```ruby request = Plaid::WatchlistScreeningEntityReviewCreateRequest.new( { confirmed_hits: ['entscrhit_52xR9LKo77r1Np'], dismissed_hits: [], entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np' } ) response = client.watchlist_screening_entity_review_create(request) ``` ```java List confirmedHits = new ArrayList(); confirmedHits.add("entscrhit_52xR9LKo77r1Np"); List dismissedHits = new ArrayList(); WatchlistScreeningEntityReviewCreateRequest request = new WatchlistScreeningEntityReviewCreateRequest() .confirmedHits(confirmedHits) .dismissedHits(dismissedHits) .entityWatchlistScreeningId("entscr_52xR9LKo77r1Np"); Response response = client() .watchlistScreeningEntityReviewCreate(request) .execute(); ``` ```python request = WatchlistScreeningEntityReviewCreateRequest( confirmed_hits=["entscrhit_52xR9LKo77r1Np"], dismissed_hits=[], entity_watchlist_screening_id="entscr_52xR9LKo77r1Np", ) response = client.watchlist_screening_entity_review_create(request) ``` ```go request := plaid.NewWatchlistScreeningEntityReviewCreateRequest( []string{"entscrhit_52xR9LKo77r1Np"}, []string{}, "entscr_52xR9LKo77r1Np", ) response, _, err := client.PlaidApi. WatchlistScreeningEntityReviewCreate(ctx). WatchlistScreeningEntityReviewCreateRequest(*request). Execute() ``` #### Response fields  string ID of the associated entity review. \[string\] Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected. \[string\] Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed. nullable, string A comment submitted by a team member as part of reviewing a watchlist screening. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "entrev_aCLNRxK3UVzn2r", "confirmed_hits": [ "enthit_52xR9LKo77r1Np" ], "dismissed_hits": [ "enthit_52xR9LKo77r1Np" ], "comment": "These look like legitimate matches, rejecting the customer.", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/entity/review/list  #### List reviews for entity watchlist screenings  List all reviews for a particular entity watchlist screening. Reviews are compliance reports created by users in your organization regarding the relevance of potential hits found by Plaid. #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string ID of the associated entity screening. string An identifier that determines which page of results you receive. ```node const request: WatchlistScreeningEntityReviewListRequest = { entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np', }; try { const response = await client.watchlistScreeningEntityReviewList(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/entity/review/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "entity_watchlist_screening_id": "entscr_52xR9LKo77r1Np" }' ``` ```ruby request = Plaid::WatchlistScreeningEntityReviewListRequest.new( { entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np' } ) response = client.watchlist_screening_entity_review_list(request) ``` ```java WatchlistScreeningEntityReviewListRequest request = new WatchlistScreeningEntityReviewListRequest() .entityWatchlistScreeningId("entscr_52xR9LKo77r1Np"); Response response = client() .watchlistScreeningEntityReviewList(request) .execute(); ``` ```python request = WatchlistScreeningEntityReviewListRequest( entity_watchlist_screening_id='entscr_52xR9LKo77r1Np', ) response = client.watchlist_screening_entity_review_list(request) ``` ```go request := plaid.NewWatchlistScreeningEntityReviewListRequest("entscr_52xR9LKo77r1Np") response, _, err := client.PlaidApi. WatchlistScreeningEntityReviewList(ctx). WatchlistScreeningEntityReviewListRequest(*request). Execute() ``` #### Response fields  \[object\] List of entity watchlist screening reviews string ID of the associated entity review. \[string\] Hits marked as a true positive after thorough manual review. These hits will never recur or be updated once dismissed. In most cases, confirmed hits indicate that the customer should be rejected. \[string\] Hits marked as a false positive after thorough manual review. These hits will never recur or be updated once dismissed. nullable, string A comment submitted by a team member as part of reviewing a watchlist screening. object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "entity_watchlist_screening_reviews": [ { "id": "entrev_aCLNRxK3UVzn2r", "confirmed_hits": [ "enthit_52xR9LKo77r1Np" ], "dismissed_hits": [ "enthit_52xR9LKo77r1Np" ], "comment": "These look like legitimate matches, rejecting the customer.", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/entity/hit/list  #### List hits for entity watchlist screenings  List all hits for the entity watchlist screening. #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string ID of the associated entity screening. string An identifier that determines which page of results you receive. ```node const request: WatchlistScreeningEntityHitListRequest = { entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np', }; try { const response = await client.watchlistScreeningEntityHitList(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/entity/hit/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "entity_watchlist_screening_id": "entscr_52xR9LKo77r1Np" }' ``` ```ruby request = Plaid::WatchlistScreeningEntityHitListRequest.new( { entity_watchlist_screening_id: 'entscr_52xR9LKo77r1Np' } ) response = client.watchlist_screening_entity_hit_list(request) ``` ```java WatchlistScreeningEntityHitListRequest request = new WatchlistScreeningEntityHitListRequest() .entityWatchlistScreeningId("entscr_52xR9LKo77r1Np"); Response response = client() .watchlistScreeningEntityHitList(request) .execute(); ``` ```python request = WatchlistScreeningEntityHitListRequest( entity_watchlist_screening_id='entscr_52xR9LKo77r1Np', ) response = client.watchlist_screening_entity_hit_list(request) ``` ```go request := plaid.NewWatchlistScreeningEntityHitListRequest("entscr_52xR9LKo77r1Np") response, _, err := client.PlaidApi. WatchlistScreeningEntityHitList(ctx). WatchlistScreeningEntityHitListRequest(*request). Execute() ``` #### Response fields  \[object\] List of entity watchlist screening hits string ID of the associated entity screening hit. string The current state of review. All watchlist screening hits begin in a `pending_review` state but can be changed by creating a review. When a hit is in the `pending_review` state, it will always show the latest version of the watchlist data Plaid has available and be compared against the latest customer information saved in the watchlist screening. Once a hit has been marked as `confirmed` or `dismissed` it will no longer be updated so that the state is as it was when the review was first conducted. Possible values: `confirmed`, `pending_review`, `dismissed` string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` nullable, string An ISO8601 formatted timestamp. Format: `date-time` string Shorthand identifier for a specific screening list for entities. `AU_CON`: Australia Department of Foreign Affairs and Trade Consolidated List `CA_CON`: Government of Canada Consolidated List of Sanctions `EU_CON`: European External Action Service Consolidated List `IZ_SOE`: State Owned Enterprise List `IZ_UNC`: United Nations Consolidated Sanctions `IZ_WBK`: World Bank Listing of Ineligible Firms and Individuals `US_CAP`: US OFAC Correspondent Account or Payable-Through Account Sanctions `US_FSE`: US OFAC Foreign Sanctions Evaders `US_MBS`: US Non-SDN Menu-Based Sanctions `US_SDN`: US Specially Designated Nationals List `US_SSI`: US OFAC Sectoral Sanctions Identifications `US_CMC`: US OFAC Non-SDN Chinese Military-Industrial Complex List `US_UVL`: Bureau of Industry and Security Unverified List `US_SAM`: US System for Award Management Exclusion List `US_TEL`: US Terrorist Exclusion List `UK_HMC`: UK HM Treasury Consolidated List Possible values: `CA_CON`, `EU_CON`, `IZ_SOE`, `IZ_UNC`, `IZ_WBK`, `US_CAP`, `US_FSE`, `US_MBS`, `US_SDN`, `US_SSI`, `US_CMC`, `US_UVL`, `US_SAM`, `US_TEL`, `AU_CON`, `UK_HMC` string A universal identifier for a watchlist individual that is stable across searches and updates. nullable, string The identifier provided by the source sanction or watchlist. When one is not provided by the source, this is `null`. object Analysis information describing why a screening hit matched the provided entity information string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` integer The version of the entity screening's `search_terms` that were compared when the entity screening hit was added. entity screening hits are immutable once they have been reviewed. If changes are detected due to updates to the entity screening's `search_terms`, the associated entity program, or the list's source data prior to review, the entity screening hit will be updated to reflect those changes. object Information associated with the entity watchlist hit \[object\] Documents associated with the watchlist hit object Summary object reflecting the match result of the associated data string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object An official document, usually issued by a governing body or institution, with an associated identifier. string The kind of official document represented by this object. `bik` - Russian bank code `business_number` - A number that uniquely identifies the business within a category of businesses `imo` - Number assigned to the entity by the International Maritime Organization `other` - Any document not covered by other categories `swift` - Number identifying a bank and branch. `tax_id` - Identification issued for the purpose of collecting taxes Possible values: `bik`, `business_number`, `imo`, `other`, `swift`, `tax_id` string The numeric or alphanumeric identifier associated with this document. Must be between 4 and 32 characters long, and cannot have leading or trailing spaces. \[object\] Email addresses associated with the watchlist hit object Summary object reflecting the match result of the associated data string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Email address information for the associated entity watchlist hit string A valid email address. Must not have leading or trailing spaces and address must be RFC compliant. For more information, see [RFC 3696](https://datatracker.ietf.org/doc/html/rfc3696) . Format: `email` \[object\] Locations associated with the watchlist hit object Summary object reflecting the match result of the associated data string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Location information for the associated individual watchlist hit string The full location string, potentially including elements like street, city, postal codes and country codes. Note that this is not necessarily a complete or well-formatted address. string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. \[object\] Names associated with the watchlist hit object Summary object reflecting the match result of the associated data string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Name information for the associated entity watchlist hit string The full name of the entity. boolean Primary names are those most commonly used to refer to this entity. Only one name will ever be marked as primary. string Names that are explicitly marked as low quality either by their `source` list, or by `plaid` by a series of additional checks done by Plaid. Plaid does not ever surface a hit as a result of a weak name alone. If a name has no quality issues, this value will be `none`. Possible values: `none`, `source`, `plaid` \[object\] Phone numbers associated with the watchlist hit object Summary object reflecting the match result of the associated data string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object Phone number information associated with the entity screening hit string An enum indicating whether a phone number is a phone line or a fax line. Possible values: `phone`, `fax` string A phone number in E.164 format. \[object\] URLs associated with the watchlist hit object Summary object reflecting the match result of the associated data string An enum indicating the match type between data provided by user and data checked against an external data source. `match` indicates that the provided input data was a strong match against external data. `partial_match` indicates the data approximately matched against external data. For example, "Knope" vs. "Knope-Wyatt" for last name. `no_match` indicates that Plaid was able to perform a check against an external data source and it did not match the provided input data. `no_data` indicates that Plaid was unable to find external data to compare against the provided input data. `no_input` indicates that Plaid was unable to perform a check because no information was provided for this field by the end user. Possible values: `match`, `partial_match`, `no_match`, `no_data`, `no_input` object URLs associated with the entity screening hit string An 'http' or 'https' URL (must begin with either of those). Format: `uri` nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "entity_watchlist_screening_hits": [ { "id": "enthit_52xR9LKo77r1Np", "review_status": "pending_review", "first_active": "2020-07-24T03:26:02Z", "inactive_since": "2020-07-24T03:26:02Z", "historical_since": "2020-07-24T03:26:02Z", "list_code": "EU_CON", "plaid_uid": "uid_3NggckTimGSJHS", "source_uid": "26192ABC", "analysis": { "documents": "match", "email_addresses": "match", "locations": "match", "names": "match", "phone_numbers": "match", "urls": "match", "search_terms_version": 1 }, "data": { "documents": [ { "analysis": { "summary": "match" }, "data": { "type": "swift", "number": "C31195855" } } ], "email_addresses": [ { "analysis": { "summary": "match" }, "data": { "email_address": "user@example.com" } } ], "locations": [ { "analysis": { "summary": "match" }, "data": { "full": "Florida, US", "country": "US" } } ], "names": [ { "analysis": { "summary": "match" }, "data": { "full": "Al Qaida", "is_primary": false, "weak_alias_determination": "none" } } ], "phone_numbers": [ { "analysis": { "summary": "match" }, "data": { "type": "phone", "phone_number": "+14025671234" } } ], "urls": [ { "analysis": { "summary": "match" }, "data": { "url": "https://example.com" } } ] } } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/entity/program/get  #### Get entity watchlist screening program  Get an entity watchlist screening program #### Request fields  required, string ID of the associated entity program. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. ```node const request: WatchlistScreeningEntityProgramGetRequest = { entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H', }; try { const response = await client.watchlistScreeningEntityProgramGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/entity/program/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "entity_watchlist_program_id": "entprg_2eRPsDnL66rZ7H" }' ``` ```ruby request = Plaid::WatchlistScreeningEntityProgramGetRequest.new( { entity_watchlist_program_id: 'entprg_2eRPsDnL66rZ7H' } ) response = client.watchlist_screening_entity_program_get(request) ``` ```java WatchlistScreeningEntityProgramGetRequest request = new WatchlistScreeningEntityProgramGetRequest() .entityWatchlistProgramId("entprg_2eRPsDnL66rZ7H"); Response response = client() .watchlistScreeningEntityProgramGet(request) .execute(); ``` ```python request = WatchlistScreeningEntityProgramGetRequest( entity_watchlist_program_id='entprg_2eRPsDnL66rZ7H', ) response = client.watchlist_screening_entity_program_get(request) ``` ```go request := plaid.NewWatchlistScreeningEntityProgramGetRequest("entprg_2eRPsDnL66rZ7H") response, _, err := client.PlaidApi. WatchlistScreeningEntityProgramGet(ctx). WatchlistScreeningEntityProgramGetRequest(*request). Execute() ``` #### Response fields  string ID of the associated entity program. string An ISO8601 formatted timestamp. Format: `date-time` boolean Indicator specifying whether the program is enabled and will perform daily rescans. \[string\] Watchlists enabled for the associated program Possible values: `CA_CON`, `EU_CON`, `IZ_SOE`, `IZ_UNC`, `IZ_WBK`, `US_CAP`, `US_FSE`, `US_MBS`, `US_SDN`, `US_SSI`, `US_CMC`, `US_UVL`, `US_SAM`, `US_TEL`, `AU_CON`, `UK_HMC` string A name for the entity program to define its purpose. For example, "High Risk Organizations" or "Applicants". string The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity. `coarse` - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review. `balanced` - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise. `strict` - Aggressive false positive reduction. This sensitivity will require names to be more similar than `coarse` and `balanced` settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations. `exact` - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case. Possible values: `coarse`, `balanced`, `strict`, `exact` object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` boolean Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "id": "entprg_2eRPsDnL66rZ7H", "created_at": "2020-07-24T03:26:02Z", "is_rescanning_enabled": true, "lists_enabled": [ "EU_CON" ], "name": "Sample Program", "name_sensitivity": "balanced", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "is_archived": false, "request_id": "saKrIBuEB9qJZng" } ``` \=\*=\*=\*= #### /watchlist\_screening/entity/program/list  #### List entity watchlist screening programs  List all entity watchlist screening programs #### Request fields  string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string An identifier that determines which page of results you receive. ```node try { const response = await client.watchlistScreeningEntityProgramList({}); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/watchlist_screening/entity/program/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}" }' ``` ```ruby response = client.watchlist_screening_entity_program_list({}) ``` ```java Response response = client() .watchlistScreeningEntityProgramList(new Object()) .execute(); ``` ```python request = WatchlistScreeningEntityProgramListRequest( cursor='eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM', ) response = client.watchlist_screening_entity_program_list(request) ``` ```go request := plaid.NewWatchlistScreeningEntityProgramsListRequest() response, _, err := client.PlaidApi. WatchlistScreeningEntityProgramList(ctx). WatchlistScreeningEntityProgramsListRequest(*request). Execute() ``` #### Response fields  \[object\] List of entity watchlist screening programs string ID of the associated entity program. string An ISO8601 formatted timestamp. Format: `date-time` boolean Indicator specifying whether the program is enabled and will perform daily rescans. \[string\] Watchlists enabled for the associated program Possible values: `CA_CON`, `EU_CON`, `IZ_SOE`, `IZ_UNC`, `IZ_WBK`, `US_CAP`, `US_FSE`, `US_MBS`, `US_SDN`, `US_SSI`, `US_CMC`, `US_UVL`, `US_SAM`, `US_TEL`, `AU_CON`, `UK_HMC` string A name for the entity program to define its purpose. For example, "High Risk Organizations" or "Applicants". string The valid name matching sensitivity configurations for a screening program. Note that while certain matching techniques may be more prevalent on less strict settings, all matching algorithms are enabled for every sensitivity. `coarse` - See more potential matches. This sensitivity will see more broad phonetic matches across alphabets that make missing a potential hit very unlikely. This setting is noisier and will require more manual review. `balanced` - A good default for most companies. This sensitivity is balanced to show high quality hits with reduced noise. `strict` - Aggressive false positive reduction. This sensitivity will require names to be more similar than `coarse` and `balanced` settings, relying less on phonetics, while still accounting for character transpositions, missing tokens, and other common permutations. `exact` - Matches must be nearly exact. This sensitivity will only show hits with exact or nearly exact name matches with only basic correction such as extraneous symbols and capitalization. This setting is generally not recommended unless you have a very specific use case. Possible values: `coarse`, `balanced`, `strict`, `exact` object Information about the last change made to the parent object specifying what caused the change as well as when it occurred. string A type indicating whether a dashboard user, an API-based user, or Plaid last touched this object. Possible values: `dashboard`, `link`, `api`, `system` nullable, string ID of the associated user. To retrieve the email address or other details of the person corresponding to this id, use `/dashboard_user/get`. string An ISO8601 formatted timestamp. Format: `date-time` boolean Archived programs are read-only and cannot screen new customers nor participate in ongoing monitoring. nullable, string An identifier that determines which page of results you receive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "entity_watchlist_programs": [ { "id": "entprg_2eRPsDnL66rZ7H", "created_at": "2020-07-24T03:26:02Z", "is_rescanning_enabled": true, "lists_enabled": [ "EU_CON" ], "name": "Sample Program", "name_sensitivity": "balanced", "audit_trail": { "source": "dashboard", "dashboard_user_id": "54350110fedcbaf01234ffee", "timestamp": "2020-07-24T03:26:02Z" }, "is_archived": false } ], "next_cursor": "eyJkaXJlY3Rpb24iOiJuZXh0Iiwib2Zmc2V0IjoiMTU5NDM", "request_id": "saKrIBuEB9qJZng" } ``` ### Webhooks  \=\*=\*=\*= #### SCREENING: STATUS\_UPDATED  Fired when an individual screening status has changed, which can occur manually via the dashboard or during ongoing monitoring. #### Properties  string `SCREENING` string `STATUS_UPDATED` string The ID of the associated screening. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "SCREENING", "webhook_code": "STATUS_UPDATED", "screening_id": "scr_52xR9LKo77r1Np", "environment": "production" } ``` \=\*=\*=\*= #### ENTITY\_SCREENING: STATUS\_UPDATED  Fired when an entity screening status has changed, which can occur manually via the dashboard or during ongoing monitoring. #### Properties  string `ENTITY_SCREENING` string `STATUS_UPDATED` string The ID of the associated entity screening. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "ENTITY_SCREENING", "webhook_code": "STATUS_UPDATED", "screening_id": "entscr_52xR9LKo77r1Np", "environment": "production" } ``` --- # API - Payment Initiation (Europe) | Plaid Docs Payment Initiation (UK and Europe)  =================================== #### API reference for Payment Initiation endpoints and webhooks  Make payment transfers from your app. Plaid supports both domestic payments denominated in local currencies and international payments, generally denominated in Euro. Domestic payments can be made in pound sterling (typically via the Faster Payments network), Euro (via SEPA Credit Transfer or SEPA Instant) and other local currencies (Polish Zloty, Danish Krone, Swedish Krona, Norwegian Krone), typically via local payment schemes. For payments in the US, see [Transfer](https://plaid.com/docs/api/products/transfer/index.html.md) . Looking for guidance on how to integrate using these endpoints? Check out the [Payment Initiation documentation](https://plaid.com/docs/payment-initiation/index.html.md) . | Endpoints | | | --- | --- | | [/payment\_initiation/recipient/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientcreate) | Create a recipient | | [/payment\_initiation/recipient/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientget) | Fetch recipient data | | [/payment\_initiation/recipient/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientlist) | List all recipients | | [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) | Create a payment | | [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) | Fetch a payment | | [/payment\_initiation/payment/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentlist) | List all payments | | [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) | Refund a payment from a virtual account | | [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) | Create a payment consent | | [/payment\_initiation/consent/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentget) | Fetch a payment consent | | [/payment\_initiation/consent/revoke](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentrevoke) | Revoke a payment consent | | [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) | Execute a payment using payment consent | Users will be prompted to authorise the payment once you [initialise Link](https://plaid.com/docs/link/index.html.md#initializing-link) . See [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) for more information on how to obtain a payments `link_token`. | See also | | | --- | --- | | [/sandbox/payment/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpaymentsimulate) | Simulate a payment in Sandbox | | [/wallet/create](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletcreate) | Create a virtual account | | [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) | Fetch a virtual account | | [/wallet/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletlist) | List all virtual accounts | | [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) | Execute a transaction | | [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) | Fetch a transaction | | [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) | List all transactions | | [WALLET\_TRANSACTION\_STATUS\_UPDATE](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) | The status of a transaction has changed | | Webhooks | | | --- | --- | | [PAYMENT\_STATUS\_UPDATE](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_status_update) | The status of a payment has changed | | [CONSENT\_STATUS\_UPDATE](https://plaid.com/docs/api/products/payment-initiation/index.html.md#consent_status_update) | The status of a consent has changed | ### Endpoints  \=\*=\*=\*= #### /payment\_initiation/recipient/create  #### Create payment recipient  Create a payment recipient for payment initiation. The recipient must be in Europe, within a country that is a member of the Single Euro Payment Area (SEPA) or a non-Eurozone country [supported](https://plaid.com/global) by Plaid. For a standing order (recurring) payment, the recipient must be in the UK. It is recommended to use `bacs` in the UK and `iban` in EU. The endpoint is idempotent: if a developer has already made a request with the same payment details, Plaid will return the same `recipient_id`. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The name of the recipient. We recommend using strings of length 18 or less and avoid special characters to ensure compatibility with all institutions. Min length: `1` string The International Bank Account Number (IBAN) for the recipient. If BACS data is not provided, an IBAN is required. Min length: `15` Max length: `34` object An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` object The optional address of the payment recipient's bank account. Required by most institutions outside of the UK. required, \[string\] An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: `1` Min length: `1` required, string The city where the recipient is located. Maximum of 35 characters. Min length: `1` Max length: `35` required, string The postal code where the recipient is located. Maximum of 16 characters. Min length: `1` Max length: `16` required, string The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: `2` Max length: `2` ```node // Using BACS, without IBAN or address const request: PaymentInitiationRecipientCreateRequest = { name: 'John Doe', bacs: { account: '26207729', sort_code: '560029', }, }; try { const response = await plaidClient.paymentInitiationRecipientCreate(request); const recipientID = response.data.recipient_id; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/payment_initiation/recipient/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "name": String, "iban": String, "bacs": Object, "address": Object }' ``` ```ruby request = Plaid::PaymentInitiationRecipientCreateRequest.new( { name: "John Doe", iban: "GB33BUKB20201555555555", address: { street: ["Street Name 999"], city: "City", postal_code: "99999", country: "GB", }, bacs: { account: "26207729", sort_code: "560029", } } ) response = client.payment_initiation_recipient_create(request) recipient_id = response.recipient_id ``` ```java PaymentInitiationAddress address = new PaymentInitiationAddress() .street(Arrays.asList("Street Name 999")) .city("City") .postalCode("99999") .country("GB"); NullableRecipientBACS bacs = new NullableRecipientBACS() .account("26207729") .sortCode("560029"); PaymentInitiationRecipientCreateRequest request = new PaymentInitiationRecipientCreateRequest() .name("John Doe") .bacs(bacs) .address(address); Response response = client .paymentInitiationRecipientCreate(request) .execute(); ``` ```python request = PaymentInitiationRecipientCreateRequest( name='John Doe', iban='GB33BUKB20201555555555', address=PaymentInitiationAddress( street=['street name 999'], city='city', postal_code='99999', country='GB' ) ) response = client.payment_initiation_recipient_create(request) recipient_id = response["recipient_id"] ``` ```go request := plaid.NewPaymentInitiationRecipientCreateRequest("John Doe") request.SetBacs(plaid.RecipientBACSNullable{ Account: plaid.PtrString("26207729"), SortCode: plaid.PtrString("560029"), }) request.SetAddress(plaid.PaymentInitiationAddress{ Street: []string{"Street Name 999"}, City: "City", PostalCode: "99999", Country: "GB", }) paymentRecipientCreateResp, _, err := client.PlaidApi.PaymentInitiationRecipientCreate(ctx).PaymentInitiationRecipientCreateRequest(*request).Execute() recipientID := paymentRecipientCreateResp.GetRecipientId() ``` #### Response fields  string A unique ID identifying the recipient string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6", "request_id": "4zlKapIkTm8p5KM" } ``` \=\*=\*=\*= #### /payment\_initiation/recipient/get  #### Get payment recipient  Get details about a payment recipient you have previously created. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the recipient ```python request = PaymentInitiationRecipientGetRequest(recipient_id=recipient_id) response = client.payment_initiation_recipient_get(request) recipient_id = response["recipient_id"] name = response["name"] iban = response["iban"] address = response["address"] ``` ```bash curl -X POST https://sandbox.plaid.com/payment_initiation/recipient/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "recipient_id": String }' ``` ```go request := plaid.NewPaymentInitiationRecipientGetRequest(recipientID) response, _, err := client.PlaidApi.PaymentInitiationRecipientGet(ctx).PaymentInitiationRecipientGetRequest(*request).Execute() name := response.GetName() iban := response.GetIban() address := response.GetAddress() ``` ```java PaymentInitiationRecipientGetRequest request = new PaymentInitiationRecipientGetRequest() .recipientId(recipientId); Response getRecipientResponse = client() .paymentInitiationRecipientGet(request) .execute(); ``` ```ruby request = Plaid::PaymentInitiationRecipientGetRequest.new({ recipient_id: recipient_id }) response = client.payment_initiation_recipient_get(request) recipient_id = response.recipient_id name = response.name iban = response.iban address = response.address ``` ```node const request: PaymentInitiationRecipientGetRequest = { recipient_id: recipientID, }; try { const response = await plaidClient.paymentInitiationRecipientGet(request); const recipientID = response.data.recipient_id; const name = response.data.name; const iban = response.data.iban; const address = response.data.address; } catch (error) { // handle error } ``` #### Response fields  string The ID of the recipient. string The name of the recipient. nullable, object The optional address of the payment recipient's bank account. Required by most institutions outside of the UK. \[string\] An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: `1` Min length: `1` string The city where the recipient is located. Maximum of 35 characters. Min length: `1` Max length: `35` string The postal code where the recipient is located. Maximum of 16 characters. Min length: `1` Max length: `16` string The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: `2` Max length: `2` nullable, string The International Bank Account Number (IBAN) for the recipient. nullable, object An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6", "name": "Wonder Wallet", "iban": "GB29NWBK60161331926819", "address": { "street": [ "96 Guild Street", "9th Floor" ], "city": "London", "postal_code": "SE14 8JW", "country": "GB" }, "request_id": "4zlKapIkTm8p5KM" } ``` \=\*=\*=\*= #### /payment\_initiation/recipient/list  #### List payment recipients  The [/payment\_initiation/recipient/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientlist) endpoint list the payment recipients that you have previously created. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. integer The maximum number of recipients to return. If `count` is not specified, a maximum of 100 recipients will be returned, beginning with the recipient at the cursor (if specified). Minimum: `1` Maximum: `100` Default: `100` string A value representing the latest recipient to be included in the response. Set this from `next_cursor` received from the previous `/payment_initiation/recipient/list` request. If provided, the response will only contain that recipient and recipients created before it. If omitted, the response will contain recipients starting from the most recent, and in descending order by the `created_at` time. Max length: `256` ```node try { const response = await plaidClient.paymentInitiationRecipientList({}); const recipients = response.data.recipients; } catch (error) { // handle error } ``` ```go request := plaid.NewPaymentInitiationRecipientListRequest() response, _, err := client.PlaidApi.PaymentInitiationRecipientList(ctx).PaymentInitiationRecipientListRequest(*request).Execute() recipients := response.GetRecipients() ``` ```python request = PaymentInitiationRecipientListRequest() response = client.payment_initiation_recipient_list(request) recipients = response["recipients"] ``` ```bash curl -X POST https://sandbox.plaid.com/payment_initiation/recipient/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}" }' ``` ```java PaymentInitiationRecipientListRequest request = new PaymentInitiationRecipientListRequest(); Response listRecipientResponse = client() .paymentInitiationRecipientList(request) .execute(); ``` ```ruby request = Plaid::PaymentInitiationRecipientListRequest.new response = client.payment_initiation_recipient_list(request) recipients = response.recipients ``` #### Response fields  \[object\] An array of payment recipients created for Payment Initiation string The ID of the recipient. string The name of the recipient. nullable, object The optional address of the payment recipient's bank account. Required by most institutions outside of the UK. \[string\] An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: `1` Min length: `1` string The city where the recipient is located. Maximum of 35 characters. Min length: `1` Max length: `35` string The postal code where the recipient is located. Maximum of 16 characters. Min length: `1` Max length: `16` string The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: `2` Max length: `2` nullable, string The International Bank Account Number (IBAN) for the recipient. nullable, object An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. string The value that, when used as the optional `cursor` parameter to `/payment_initiation/recipient/list`, will return the corresponding recipient as its first recipient. Max length: `256` Response Object ```json { "recipients": [ { "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6", "name": "Wonder Wallet", "iban": "GB29NWBK60161331926819", "address": { "street": [ "96 Guild Street", "9th Floor" ], "city": "London", "postal_code": "SE14 8JW", "country": "GB" } } ], "next_cursor": "YWJjMTIzIT8kKiYoKSctPUE", "request_id": "4zlKapIkTm8p5KM" } ``` \=\*=\*=\*= #### /payment\_initiation/payment/create  #### Create a payment  After creating a payment recipient, you can use the [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) endpoint to create a payment to that recipient. Payments can be one-time or standing order (recurring) and can be denominated in either EUR, GBP or other chosen [currency](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiation-payment-create-request-amount-currency) . If making domestic GBP-denominated payments, your recipient must have been created with BACS numbers. In general, EUR-denominated payments will be sent via SEPA Credit Transfer, GBP-denominated payments will be sent via the Faster Payments network and for non-Eurozone markets typically via the local payment scheme, but the payment network used will be determined by the institution. Payments sent via Faster Payments will typically arrive immediately, while payments sent via SEPA Credit Transfer or other local payment schemes will typically arrive in one business day. Standing orders (recurring payments) must be denominated in GBP and can only be sent to recipients in the UK. Once created, standing order payments cannot be modified or canceled via the API. An end user can cancel or modify a standing order directly on their banking application or website, or by contacting the bank. Standing orders will follow the payment rules of the underlying rails (Faster Payments in UK). Payments can be sent Monday to Friday, excluding bank holidays. If the pre-arranged date falls on a weekend or bank holiday, the payment is made on the next working day. It is not possible to guarantee the exact time the payment will reach the recipient’s account, although at least 90% of standing order payments are sent by 6am. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the recipient the payment is for. required, string A reference for the payment. This must be an alphanumeric string with at most 18 characters and must not contain any special characters (since not all institutions support them). In order to track settlement via Payment Confirmation, each payment must have a unique reference. If the reference provided through the API is not unique, Plaid will adjust it. Some institutions may limit the reference to less than 18 characters. If necessary, Plaid will adjust the reference by truncating it to fit the institution's requirements. Both the originally provided and automatically adjusted references (if any) can be found in the `reference` and `adjusted_reference` fields, respectively. Min length: `1` Max length: `18` required, object The amount and currency of a payment required, string The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: `GBP`, `EUR`, `PLN`, `SEK`, `DKK`, `NOK` Min length: `3` Max length: `3` required, number The amount of the payment. Must contain at most two digits of precision e.g. `1.23`. Minimum accepted value is `1`. Format: `double` object The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once. required, string The frequency interval of the payment. Possible values: `WEEKLY`, `MONTHLY` Min length: `1` required, integer The day of the interval on which to schedule the payment. If the payment interval is weekly, `interval_execution_day` should be an integer from 1 (Monday) to 7 (Sunday). If the payment interval is monthly, `interval_execution_day` should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on. required, string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Standing order payments will begin on the first `interval_execution_day` on or after the `start_date`. If the first `interval_execution_day` on or after the start date is also the same day that `/payment_initiation/payment/create` was called, the bank _may_ make the first payment on that day, but it is not guaranteed to do so. Format: `date` string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Standing order payments will end on the last `interval_execution_day` on or before the `end_date`. If the only `interval_execution_day` between the start date and the end date (inclusive) is also the same day that `/payment_initiation/payment/create` was called, the bank _may_ make a payment on that day, but it is not guaranteed to do so. Format: `date` string The start date sent to the bank after adjusting for holidays or weekends. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). If the start date did not require adjustment, this field will be `null`. Format: `date` object Additional payment options boolean When `true`, Plaid will attempt to request refund details from the payee's financial institution. Support varies between financial institutions and will not always be available. If refund details could be retrieved, they will be available in the `/payment_initiation/payment/get` response. string The International Bank Account Number (IBAN) for the payer's account. Where possible, the end user will be able to send payments only from the specified bank account if provided. Min length: `15` Max length: `34` object An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` string Payment scheme. If not specified - the default in the region will be used (e.g. `SEPA_CREDIT_TRANSFER` for EU). In responses, if the scheme is not explicitly specified in the request, this value will be `null`. Using unsupported values will result in a failed payment. `LOCAL_DEFAULT`: The default payment scheme for the selected market and currency will be used. `LOCAL_INSTANT`: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. `SEPA_CREDIT_TRANSFER`: The standard payment to a beneficiary within the SEPA area. `SEPA_CREDIT_TRANSFER_INSTANT`: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks. Possible values: `null`, `LOCAL_DEFAULT`, `LOCAL_INSTANT`, `SEPA_CREDIT_TRANSFER`, `SEPA_CREDIT_TRANSFER_INSTANT` ```go request = plaid.NewPaymentInitiationPaymentCreateRequest( recipientID, "TestPayment", *plaid.NewPaymentAmount("GBP", 100.0), ) request.SetSchedule(*plaid.NewExternalPaymentScheduleRequest( plaid.PAYMENTSCHEDULEINTERVAL_MONTHLY, 1, "2020-01-01", )) response, _, err := client.PlaidApi.PaymentInitiationPaymentCreate(ctx).PaymentInitiationPaymentCreateRequest(*request).Execute() paymentID := response.GetPaymentId() ``` ```python request = PaymentInitiationPaymentCreateRequest( recipient_id=recipient_id, reference='TestPayment', amount=Amount( currency='GBP', value=100.00 ) ) response = client.payment_initiation_payment_create(request) payment_id = response["payment_id"] status = response["status"] ``` ```java Amount amount = new Amount() .currency(Amount.CurrencyEnum.GBP) .value(999.99); PaymentInitiationPaymentCreateRequest request = new PaymentInitiationPaymentCreateRequest() .recipientId(recipientId) .reference("reference") .amount(amount); Response response = client .paymentInitiationPaymentCreate(request) .execute(); ``` ```bash curl -X POST https://sandbox.plaid.com/payment_initiation/payment/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "recipient_id": String, "reference": String, "amount": Object, "schedule": Object }' ``` ```ruby request = Plaid::PaymentInitiationPaymentCreateRequest.new( { recipient_id: recipient_id, reference: "testpayment", amount: { value: 100.00, currency: "GBP" } } ) response = client.payment_initiation_payment_create(request) payment_id = response.payment_id status = response.status ``` ```node const request: PaymentInitiationPaymentCreateRequest = { recipient_id: recipientID, reference: 'TestPayment', amount: { currency: 'GBP', value: 100.0, }, }; try { const response = await plaidClient.paymentInitiationPaymentCreate(request); const paymentID = response.data.payment_id; const status = response.data.status; } catch (error) { // handle error } ``` #### Response fields  string A unique ID identifying the payment string For a payment returned by this endpoint, there is only one possible value: `PAYMENT_STATUS_INPUT_NEEDED`: The initial phase of the payment Possible values: `PAYMENT_STATUS_INPUT_NEEDED` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3", "status": "PAYMENT_STATUS_INPUT_NEEDED", "request_id": "4ciYVmesrySiUAB" } ``` \=\*=\*=\*= #### /payment\_initiation/payment/get  #### Get payment details  The [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) endpoint can be used to check the status of a payment, as well as to receive basic information such as recipient and payment amount. In the case of standing orders, the [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) endpoint will provide information about the status of the overall standing order itself; the API cannot be used to retrieve payment status for individual payments within a standing order. Polling for status updates in Production is highly discouraged. Repeatedly calling [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) to check a payment's status is unreliable and may trigger API rate limits. Only the `payment_status_update` webhook should be used to receive real-time status updates in Production. In the case of standing orders, the [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) endpoint will provide information about the status of the overall standing order itself; the API cannot be used to retrieve payment status for individual payments within a standing order. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The `payment_id` returned from `/payment_initiation/payment/create`. ```go request := plaid.NewPaymentInitiationPaymentGetRequest(paymentID) response, _, err := client.PlaidApi.PaymentInitiationPaymentGet(ctx).PaymentInitiationPaymentGetRequest(*request).Execute() paymentID := response.GetPaymentId() ``` ```java PaymentInitiationPaymentGetRequest request = new PaymentInitiationPaymentGetRequest() .paymentId(paymentId); Response response = client() .paymentInitiationPaymentGet(request) .execute(); ``` ```ruby request = Plaid::PaymentInitiationPaymentGetRequest.new({ payment_id: payment_id }) response = client.payment_initiation_payment_get(request) payment_id = response.payment_id payment_token = response.payment_token reference = response.reference amount = response.amount status = response.status last_status_update = response.last_status_update payment_token_expiration_time = response.payment_token_expiration_time recipient_id = response.recipient_id ``` ```node const request: PaymentInitiationPaymentGetRequest = { payment_id: paymentID, }; try { const response = await plaidClient.paymentInitiationPaymentGet(request); const paymentID = response.data.payment_id; const paymentToken = response.data.payment_token; const reference = response.data.reference; const amount = response.data.amount; const status = response.data.status; const lastStatusUpdate = response.data.last_status_update; const paymentTokenExpirationTime = response.data.payment_token_expiration_time; const recipientID = response.data.recipient_id; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/payment_initiation/payment/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "payment_id": String, }' ``` ```python request = PaymentInitiationPaymentGetRequest(payment_id=payment_id) response = client.payment_initiation_payment_get(request) payment_id = response["payment_id"] payment_token = response["payment_token"] reference = response["reference"] amount = response["amount"] status = response["status"] last_status_update = response["last_status_update"] payment_token_expiration_time = response["payment_token_expiration_time"] recipient_id = response["recipient_id"] ``` #### Response fields  string The ID of the payment. Like all Plaid identifiers, the `payment_id` is case sensitive. object The amount and currency of a payment string The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: `GBP`, `EUR`, `PLN`, `SEK`, `DKK`, `NOK` Min length: `3` Max length: `3` number The amount of the payment. Must contain at most two digits of precision e.g. `1.23`. Minimum accepted value is `1`. Format: `double` string The status of the payment. Core lifecycle statuses: **`PAYMENT_STATUS_INPUT_NEEDED`**: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. **`PAYMENT_STATUS_AUTHORISING`:** Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. **`PAYMENT_STATUS_INITIATED`:** The payment has been authorised and accepted by the financial institution. In many EU markets, `PAYMENT_STATUS_EXECUTED` is not supported, and a payment will remain in `PAYMENT_STATUS_INITIATED` until the funds settle, making this a terminal success state in those cases. A payment in `PAYMENT_STATUS_INITIATED` should be treated as a successfully submitted payment; do not gate downstream processing on reaching `PAYMENT_STATUS_EXECUTED`. For a full explanation of payment statuses and how to handle each, see the [Payment Status guide](https://plaid.com/docs/payment-initiation/payment-status/index.html.md) . **`PAYMENT_STATUS_EXECUTED`: Terminal.** The funds have left the payer’s account and the payment is en route to settlement. Note that this status does not confirm that funds have arrived in the recipient’s account; do not use it as proof of fund receipt. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in `PAYMENT_STATUS_INITIATED` before settling. When using Plaid Virtual Accounts, `PAYMENT_STATUS_EXECUTED` is not terminal—the payment will continue to `PAYMENT_STATUS_SETTLED` once funds are available. **`PAYMENT_STATUS_SETTLED`: Terminal.** The funds are available in the recipient’s account. Only available to customers using [Plaid Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) . Failure statuses: **`PAYMENT_STATUS_INSUFFICIENT_FUNDS`: Terminal.** The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. **`PAYMENT_STATUS_FAILED`: Terminal (retryable).** The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. **`PAYMENT_STATUS_BLOCKED`: Terminal (retryable).** The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. **`PAYMENT_STATUS_REJECTED`: Terminal.** The payment was rejected by the financial institution. No automatic retry is possible. **`PAYMENT_STATUS_CANCELLED`: Terminal.** The end user cancelled the payment during authorisation. Standing-order statuses: **`PAYMENT_STATUS_ESTABLISHED`: Terminal.** A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): `PAYMENT_STATUS_UNKNOWN`: The payment status is unknown. `PAYMENT_STATUS_PROCESSING`: The payment is currently being processed. `PAYMENT_STATUS_COMPLETED`: Indicates that the standing order has been successfully established. Possible values: `PAYMENT_STATUS_INPUT_NEEDED`, `PAYMENT_STATUS_PROCESSING`, `PAYMENT_STATUS_INITIATED`, `PAYMENT_STATUS_COMPLETED`, `PAYMENT_STATUS_INSUFFICIENT_FUNDS`, `PAYMENT_STATUS_FAILED`, `PAYMENT_STATUS_BLOCKED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_STATUS_EXECUTED`, `PAYMENT_STATUS_SETTLED`, `PAYMENT_STATUS_AUTHORISING`, `PAYMENT_STATUS_CANCELLED`, `PAYMENT_STATUS_ESTABLISHED`, `PAYMENT_STATUS_REJECTED` string The ID of the recipient string A reference for the payment. nullable, string The value of the reference sent to the bank after adjustment to pass bank validation rules. string The date and time of the last time the `status` was updated, in IS0 8601 format Format: `date-time` nullable, object The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once. string The frequency interval of the payment. Possible values: `WEEKLY`, `MONTHLY` Min length: `1` integer The day of the interval on which to schedule the payment. If the payment interval is weekly, `interval_execution_day` should be an integer from 1 (Monday) to 7 (Sunday). If the payment interval is monthly, `interval_execution_day` should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on. string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Standing order payments will begin on the first `interval_execution_day` on or after the `start_date`. If the first `interval_execution_day` on or after the start date is also the same day that `/payment_initiation/payment/create` was called, the bank _may_ make the first payment on that day, but it is not guaranteed to do so. Format: `date` nullable, string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Standing order payments will end on the last `interval_execution_day` on or before the `end_date`. If the only `interval_execution_day` between the start date and the end date (inclusive) is also the same day that `/payment_initiation/payment/create` was called, the bank _may_ make a payment on that day, but it is not guaranteed to do so. Format: `date` nullable, string The start date sent to the bank after adjusting for holidays or weekends. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). If the start date did not require adjustment, this field will be `null`. Format: `date` nullable, object Details about external payment refund string The name of the account holder. nullable, string The International Bank Account Number (IBAN) for the account. nullable, object An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` nullable, object An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` nullable, string The International Bank Account Number (IBAN) for the sender, if specified in the `/payment_initiation/payment/create` call. nullable, \[string\] Refund IDs associated with the payment. nullable, object The amount and currency of a payment string The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: `GBP`, `EUR`, `PLN`, `SEK`, `DKK`, `NOK` Min length: `3` Max length: `3` number The amount of the payment. Must contain at most two digits of precision e.g. `1.23`. Format: `double` Minimum: `0.01` nullable, string The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests. nullable, string Payment scheme. If not specified - the default in the region will be used (e.g. `SEPA_CREDIT_TRANSFER` for EU). In responses, if the scheme is not explicitly specified in the request, this value will be `null`. Using unsupported values will result in a failed payment. `LOCAL_DEFAULT`: The default payment scheme for the selected market and currency will be used. `LOCAL_INSTANT`: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. `SEPA_CREDIT_TRANSFER`: The standard payment to a beneficiary within the SEPA area. `SEPA_CREDIT_TRANSFER_INSTANT`: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks. Possible values: `null`, `LOCAL_DEFAULT`, `LOCAL_INSTANT`, `SEPA_CREDIT_TRANSFER`, `SEPA_CREDIT_TRANSFER_INSTANT` nullable, string Payment scheme. If not specified - the default in the region will be used (e.g. `SEPA_CREDIT_TRANSFER` for EU). In responses, if the scheme is not explicitly specified in the request, this value will be `null`. Using unsupported values will result in a failed payment. `LOCAL_DEFAULT`: The default payment scheme for the selected market and currency will be used. `LOCAL_INSTANT`: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. `SEPA_CREDIT_TRANSFER`: The standard payment to a beneficiary within the SEPA area. `SEPA_CREDIT_TRANSFER_INSTANT`: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks. Possible values: `null`, `LOCAL_DEFAULT`, `LOCAL_INSTANT`, `SEPA_CREDIT_TRANSFER`, `SEPA_CREDIT_TRANSFER_INSTANT` nullable, string The payment consent ID that this payment was initiated with. Is present only when payment was initiated using the payment consent. nullable, string The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts. nullable, string A unique identifier assigned by Plaid to each payment for tracking and reconciliation purposes. Note: Not all banks handle `end_to_end_id` consistently. To ensure accurate matching, clients should convert both the incoming `end_to_end_id` and the one provided by Plaid to the same case (either lower or upper) before comparison. For virtual account payments, Plaid manages this field automatically. nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3", "reference": "Account Funding 99744", "amount": { "currency": "GBP", "value": 100 }, "status": "PAYMENT_STATUS_INITIATED", "last_status_update": "2019-11-06T21:10:52Z", "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6", "bacs": { "account": "31926819", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "sort_code": "601613" }, "end_to_end_id": "sptch8cde8390bfd363888", "iban": null, "request_id": "aEAQmewMzlVa1k6" } ``` \=\*=\*=\*= #### /payment\_initiation/payment/list  #### List payments  The [/payment\_initiation/payment/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentlist) endpoint can be used to retrieve all created payments. By default, the 10 most recent payments are returned. You can request more payments and paginate through the results using the optional `count` and `cursor` parameters. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. integer The maximum number of payments to return. If `count` is not specified, a maximum of 10 payments will be returned, beginning with the most recent payment before the cursor (if specified). Minimum: `1` Maximum: `200` Default: `10` string A string in RFC 3339 format (i.e. "2019-12-06T22:35:49Z"). Only payments created before the cursor will be returned. Format: `date-time` string The consent ID. If specified, only payments, executed using this consent, will be returned. ```python request = PaymentInitiationPaymentListRequest(count=10) response = client.payment_initiation_payment_list(request) payments = response["payments"] ``` ```go request := plaid.NewPaymentInitiationPaymentListRequest() response, _, err := client.PlaidApi.PaymentInitiationPaymentList(ctx).PaymentInitiationPaymentListRequest(*request).Execute() payments := response.GetPayments() ``` ```bash curl -X POST https://sandbox.plaid.com/payment_initiation/payment/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}" }' ``` ```ruby request = Plaid::PaymentInitiationPaymentListRequest.new({ count: 10 }) response = client.payment_initiation_payment_list(request) payments = response.payments ``` ```java PaymentInitiationPaymentListRequest request = new PaymentInitiationPaymentListRequest() .count(10) .cursor("2019-12-06T22:35:49Z"); Response response = client() .paymentInitiationPaymentList(request) .execute(); ``` ```node const request: PaymentInitiationPaymentListRequest = { count: 10, cursor: '2019-12-06T22:35:49Z', }; try { const response = await plaidClient.paymentInitiationPaymentList(request); const payments = response.data.payments; const nextCursor = response.data.next_cursor; } catch (error) { // handle error } ``` #### Response fields  \[object\] An array of payments that have been created, associated with the given `client_id`. string The ID of the payment. Like all Plaid identifiers, the `payment_id` is case sensitive. object The amount and currency of a payment string The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: `GBP`, `EUR`, `PLN`, `SEK`, `DKK`, `NOK` Min length: `3` Max length: `3` number The amount of the payment. Must contain at most two digits of precision e.g. `1.23`. Minimum accepted value is `1`. Format: `double` string The status of the payment. Core lifecycle statuses: **`PAYMENT_STATUS_INPUT_NEEDED`**: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. **`PAYMENT_STATUS_AUTHORISING`:** Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. **`PAYMENT_STATUS_INITIATED`:** The payment has been authorised and accepted by the financial institution. In many EU markets, `PAYMENT_STATUS_EXECUTED` is not supported, and a payment will remain in `PAYMENT_STATUS_INITIATED` until the funds settle, making this a terminal success state in those cases. A payment in `PAYMENT_STATUS_INITIATED` should be treated as a successfully submitted payment; do not gate downstream processing on reaching `PAYMENT_STATUS_EXECUTED`. For a full explanation of payment statuses and how to handle each, see the [Payment Status guide](https://plaid.com/docs/payment-initiation/payment-status/index.html.md) . **`PAYMENT_STATUS_EXECUTED`: Terminal.** The funds have left the payer’s account and the payment is en route to settlement. Note that this status does not confirm that funds have arrived in the recipient’s account; do not use it as proof of fund receipt. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in `PAYMENT_STATUS_INITIATED` before settling. When using Plaid Virtual Accounts, `PAYMENT_STATUS_EXECUTED` is not terminal—the payment will continue to `PAYMENT_STATUS_SETTLED` once funds are available. **`PAYMENT_STATUS_SETTLED`: Terminal.** The funds are available in the recipient’s account. Only available to customers using [Plaid Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) . Failure statuses: **`PAYMENT_STATUS_INSUFFICIENT_FUNDS`: Terminal.** The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. **`PAYMENT_STATUS_FAILED`: Terminal (retryable).** The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. **`PAYMENT_STATUS_BLOCKED`: Terminal (retryable).** The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. **`PAYMENT_STATUS_REJECTED`: Terminal.** The payment was rejected by the financial institution. No automatic retry is possible. **`PAYMENT_STATUS_CANCELLED`: Terminal.** The end user cancelled the payment during authorisation. Standing-order statuses: **`PAYMENT_STATUS_ESTABLISHED`: Terminal.** A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): `PAYMENT_STATUS_UNKNOWN`: The payment status is unknown. `PAYMENT_STATUS_PROCESSING`: The payment is currently being processed. `PAYMENT_STATUS_COMPLETED`: Indicates that the standing order has been successfully established. Possible values: `PAYMENT_STATUS_INPUT_NEEDED`, `PAYMENT_STATUS_PROCESSING`, `PAYMENT_STATUS_INITIATED`, `PAYMENT_STATUS_COMPLETED`, `PAYMENT_STATUS_INSUFFICIENT_FUNDS`, `PAYMENT_STATUS_FAILED`, `PAYMENT_STATUS_BLOCKED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_STATUS_EXECUTED`, `PAYMENT_STATUS_SETTLED`, `PAYMENT_STATUS_AUTHORISING`, `PAYMENT_STATUS_CANCELLED`, `PAYMENT_STATUS_ESTABLISHED`, `PAYMENT_STATUS_REJECTED` string The ID of the recipient string A reference for the payment. nullable, string The value of the reference sent to the bank after adjustment to pass bank validation rules. string The date and time of the last time the `status` was updated, in IS0 8601 format Format: `date-time` nullable, object The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once. string The frequency interval of the payment. Possible values: `WEEKLY`, `MONTHLY` Min length: `1` integer The day of the interval on which to schedule the payment. If the payment interval is weekly, `interval_execution_day` should be an integer from 1 (Monday) to 7 (Sunday). If the payment interval is monthly, `interval_execution_day` should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on. string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Standing order payments will begin on the first `interval_execution_day` on or after the `start_date`. If the first `interval_execution_day` on or after the start date is also the same day that `/payment_initiation/payment/create` was called, the bank _may_ make the first payment on that day, but it is not guaranteed to do so. Format: `date` nullable, string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). Standing order payments will end on the last `interval_execution_day` on or before the `end_date`. If the only `interval_execution_day` between the start date and the end date (inclusive) is also the same day that `/payment_initiation/payment/create` was called, the bank _may_ make a payment on that day, but it is not guaranteed to do so. Format: `date` nullable, string The start date sent to the bank after adjusting for holidays or weekends. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). If the start date did not require adjustment, this field will be `null`. Format: `date` nullable, object Details about external payment refund string The name of the account holder. nullable, string The International Bank Account Number (IBAN) for the account. nullable, object An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` nullable, object An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` nullable, string The International Bank Account Number (IBAN) for the sender, if specified in the `/payment_initiation/payment/create` call. nullable, \[string\] Refund IDs associated with the payment. nullable, object The amount and currency of a payment string The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: `GBP`, `EUR`, `PLN`, `SEK`, `DKK`, `NOK` Min length: `3` Max length: `3` number The amount of the payment. Must contain at most two digits of precision e.g. `1.23`. Format: `double` Minimum: `0.01` nullable, string The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests. nullable, string Payment scheme. If not specified - the default in the region will be used (e.g. `SEPA_CREDIT_TRANSFER` for EU). In responses, if the scheme is not explicitly specified in the request, this value will be `null`. Using unsupported values will result in a failed payment. `LOCAL_DEFAULT`: The default payment scheme for the selected market and currency will be used. `LOCAL_INSTANT`: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. `SEPA_CREDIT_TRANSFER`: The standard payment to a beneficiary within the SEPA area. `SEPA_CREDIT_TRANSFER_INSTANT`: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks. Possible values: `null`, `LOCAL_DEFAULT`, `LOCAL_INSTANT`, `SEPA_CREDIT_TRANSFER`, `SEPA_CREDIT_TRANSFER_INSTANT` nullable, string Payment scheme. If not specified - the default in the region will be used (e.g. `SEPA_CREDIT_TRANSFER` for EU). In responses, if the scheme is not explicitly specified in the request, this value will be `null`. Using unsupported values will result in a failed payment. `LOCAL_DEFAULT`: The default payment scheme for the selected market and currency will be used. `LOCAL_INSTANT`: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. `SEPA_CREDIT_TRANSFER`: The standard payment to a beneficiary within the SEPA area. `SEPA_CREDIT_TRANSFER_INSTANT`: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks. Possible values: `null`, `LOCAL_DEFAULT`, `LOCAL_INSTANT`, `SEPA_CREDIT_TRANSFER`, `SEPA_CREDIT_TRANSFER_INSTANT` nullable, string The payment consent ID that this payment was initiated with. Is present only when payment was initiated using the payment consent. nullable, string The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts. nullable, string A unique identifier assigned by Plaid to each payment for tracking and reconciliation purposes. Note: Not all banks handle `end_to_end_id` consistently. To ensure accurate matching, clients should convert both the incoming `end_to_end_id` and the one provided by Plaid to the same case (either lower or upper) before comparison. For virtual account payments, Plaid manages this field automatically. nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. nullable, string The value that, when used as the optional `cursor` parameter to `/payment_initiation/payment/list`, will return the next unreturned payment as its first payment. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "payments": [ { "payment_id": "payment-id-sandbox-feca8a7a-5581-4aef-9297-f3062bb735d3", "reference": "Account Funding 99744", "amount": { "currency": "GBP", "value": 100 }, "status": "PAYMENT_STATUS_EXECUTED", "last_status_update": "2019-11-06T21:10:52Z", "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6", "bacs": { "account": "31926819", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "sort_code": "601613" }, "iban": "null,", "end_to_end_id": "sptch8cde8390bfd363888," } ], "next_cursor": "2020-01-01T00:00:00Z", "request_id": "aEAQmewMzlVa1k6" } ``` \=\*=\*=\*= #### /payment\_initiation/payment/reverse  #### Reverse an existing payment  Reverse a settled payment from a Plaid virtual account. The original payment must be in a settled state to be refunded. To refund partially, specify the amount as part of the request. If the amount is not specified, the refund amount will be equal to all of the remaining payment amount that has not been refunded yet. The refund will go back to the source account that initiated the payment. The original payment must have been initiated to a Plaid virtual account so that this account can be used to initiate the refund. Providing counterparty information such as date of birth and address increases the likelihood of refund being successful without human intervention. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the payment to reverse required, string A random key provided by the client, per unique wallet transaction. Maximum of 128 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a wallet transaction fails due to a network connection error, then after a minimum delay of one minute, you can retry the request with the same idempotency key to guarantee that only a single wallet transaction is created. If the request was successfully processed, it will prevent any transaction that uses the same idempotency key, and was received within 24 hours of the first request, from being processed. Max length: `128` Min length: `1` required, string A reference for the refund. This must be an alphanumeric string with 6 to 18 characters and must not contain any special characters or spaces. Max length: `18` Min length: `6` object The amount and currency of a payment required, string The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: `GBP`, `EUR`, `PLN`, `SEK`, `DKK`, `NOK` Min length: `3` Max length: `3` required, number The amount of the payment. Must contain at most two digits of precision e.g. `1.23`. Format: `double` Minimum: `0.01` string The counterparty's birthdate, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format. Format: `date` object The optional address of the payment recipient's bank account. Required by most institutions outside of the UK. required, \[string\] An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: `1` Min length: `1` required, string The city where the recipient is located. Maximum of 35 characters. Min length: `1` Max length: `35` required, string The postal code where the recipient is located. Maximum of 16 characters. Min length: `1` Max length: `16` required, string The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: `2` Max length: `2` ```python request = PaymentInitiationPaymentReverseRequest( payment_id=payment_id, reference='Refund for purchase ABC123', idempotency_key='ae009325-df8d-4f52-b1e0-53ff26c23912' ) response = client.payment_initiation_payment_reverse(request) refund_id = response['refund_id'] status = response['status'] ``` ```go request := plaid.NewPaymentInitiationPaymentReverseRequest( paymentID, "ae009325-df8d-4f52-b1e0-53ff26c23912", "Refund for purchase ABC123", ) response, _, err := client.PlaidApi.PaymentInitiationPaymentReverse(ctx).PaymentInitiationPaymentReverseRequest(*request).Execute() refundID := response.GetRefundId() status := response.GetStatus() ``` ```bash curl -X POST https://production.plaid.com/payment_initiation/payment/reverse \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "payment_id": "${PAYMENT_ID}", "reference": "Refund for purchase ABC123", "idempotency_key": "ae009325-df8d-4f52-b1e0-53ff26c23912" }' ``` ```ruby request = Plaid::PaymentInitiationPaymentReverseRequest.new( { payment_id: payment_id, reference: 'Refund for purchase ABC123', idempotency_key: 'ae009325-df8d-4f52-b1e0-53ff26c23912' } ) response = client.payment_initiation_payment_reverse(request) refund_id = response.refund_id status = response.status ``` ```java PaymentInitiationPaymentReverseRequest request = new PaymentInitiationPaymentReverseRequest() .paymentId(paymentId) .reference("Refund for purchase ABC123") .idempotencyKey("ae009325-df8d-4f52-b1e0-53ff26c23912"); Response response = client() .paymentInitiationPaymentReverse(request) .execute(); String refundId = response.body().getRefundId(); PaymentInitiationRefundStatus status = response.body().getStatus(); ``` ```node const request: PaymentInitiationPaymentReverseRequest = { payment_id: paymentID, reference: 'Refund for purchase ABC123', idempotency_key: 'ae009325-df8d-4f52-b1e0-53ff26c23912', }; try { const response = await plaidClient.paymentInitiationPaymentReverse(request); const refundID = response.data.refund_id; const status = response.data.status; } catch (error) { // handle error } ``` #### Response fields  string A unique ID identifying the refund string The status of the transaction. `AUTHORISING`: The transaction is being processed for validation and compliance. `INITIATED`: The transaction has been initiated and is currently being processed. `EXECUTED`: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. `SETTLED`: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. `FAILED`: The transaction failed to process successfully. This is a terminal status. `BLOCKED`: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: `AUTHORISING`, `INITIATED`, `EXECUTED`, `SETTLED`, `BLOCKED`, `FAILED` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "refund_id": "wallet-transaction-id-production-c5f8cd31-6cae-4cad-9b0d-f7c10be9cc4b", "request_id": "HtlKzBX0fMeF7mU", "status": "INITIATED" } ``` \=\*=\*=\*= #### /payment\_initiation/consent/create  #### Create payment consent  The [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) endpoint is used to create a payment consent, which can be used to initiate payments on behalf of the user. Payment consents are created with `UNAUTHORISED` status by default and must be authorised by the user before payments can be initiated. Consents can be limited in time and scope, and have constraints that describe limitations for payments. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the recipient the payment consent is for. The created consent can be used to transfer funds to this recipient only. required, string A reference for the payment consent. This must be an alphanumeric string with at most 18 characters and must not contain any special characters. Min length: `1` Max length: `18` deprecated, \[string\] An array of payment consent scopes. Min items: `1` Possible values: `ME_TO_ME`, `EXTERNAL` string Payment consent type. Defines possible use case for payments made with the given consent. `SWEEPING`: Allows moving money between accounts owned by the same user. `COMMERCIAL`: Allows initiating payments from the user's account to third parties. Possible values: `SWEEPING`, `COMMERCIAL` required, object Limitations that will be applied to payments initiated using the payment consent. object Life span for the payment consent. After the `to` date the payment consent expires and can no longer be used for payment initiation. string The date and time from which the consent should be active, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` string The date and time at which the consent expires, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` required, object Maximum amount of a single payment initiated using the payment consent. required, string The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: `GBP`, `EUR`, `PLN`, `SEK`, `DKK`, `NOK` Min length: `3` Max length: `3` required, number The amount of the payment. Must contain at most two digits of precision e.g. `1.23`. Minimum accepted value is `1`. Format: `double` required, \[object\] A list of amount limitations per period of time. Min items: `1` required, object Maximum cumulative amount for all payments in the specified interval. required, string The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: `GBP`, `EUR`, `PLN`, `SEK`, `DKK`, `NOK` Min length: `3` Max length: `3` required, number The amount of the payment. Must contain at most two digits of precision e.g. `1.23`. Minimum accepted value is `1`. Format: `double` required, string Payment consent periodic interval. Possible values: `DAY`, `WEEK`, `MONTH`, `YEAR` required, string Where the payment consent period should start. If the institution is Monzo, only `CONSENT` alignments are supported. `CALENDAR`: line up with a calendar. `CONSENT`: on the date of consent creation. Possible values: `CALENDAR`, `CONSENT` deprecated, object (Deprecated) Additional payment consent options. Please use `payer_details` to specify the account. boolean When `true`, Plaid will attempt to request refund details from the payee's financial institution. Support varies between financial institutions and will not always be available. If refund details could be retrieved, they will be available in the `/payment_initiation/payment/get` response. string The International Bank Account Number (IBAN) for the payer's account. Where possible, the end user will be able to set up payment consent using only the specified bank account if provided. Min length: `15` Max length: `34` object An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` object An object representing the payment consent payer details. Payer `name` and account `numbers` are required to lock the account to which the consent can be created. required, string The name of the payer as it appears in their bank account Min length: `1` required, object The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required. object An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` string International Bank Account Number (IBAN). Min length: `15` Max length: `34` object The optional address of the payment recipient's bank account. Required by most institutions outside of the UK. required, \[string\] An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: `1` Min length: `1` required, string The city where the recipient is located. Maximum of 35 characters. Min length: `1` Max length: `35` required, string The postal code where the recipient is located. Maximum of 16 characters. Min length: `1` Max length: `16` required, string The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: `2` Max length: `2` string The payer's birthdate, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format. Format: `date` \[string\] The payer's phone numbers in E.164 format: +{countrycode}{number} \[string\] The payer's emails ```python request = PaymentInitiationConsentCreateRequest( recipient_id=recipient_id, reference="TestPaymentConsent", type="COMMERCIAL", constraints=PaymentInitiationConsentConstraints( valid_date_time=PaymentConsentValidDateTime(to="2024-12-31T23:59:59Z"), max_payment_amount=PaymentConsentMaxPaymentAmount(currency="GBP",value=15.00), periodic_amounts=[ PaymentConsentPeriodicAmount( amount=PaymentConsentPeriodicAmountAmount(currency="GBP",value=40.00), interval=PaymentConsentPeriodicInterval("MONTH"), alignment=PaymentConsentPeriodicAlignment("CALENDAR") ) ] ) ) response = client.payment_initiation_consent_create(request) consent_id = response["consent_id"] status = response["status"] ``` ```go constraints := plaid.NewPaymentInitiationConsentConstraints( *plaid.NewPaymentConsentMaxPaymentAmount("GBP", 15), []plaid.PaymentConsentPeriodicAmount{ *plaid.NewPaymentConsentPeriodicAmount( *plaid.NewPaymentConsentPeriodicAmountAmount("GBP", 40), plaid.PAYMENTCONSENTPERIODICINTERVAL_MONTH, plaid.PAYMENTCONSENTPERIODICALIGNMENT_CALENDAR, ), }, ) consentValidDateTime := plaid.NewPaymentConsentValidDateTime() validUntil := time.Date(2024, time.December, 31, 23, 59, 59, 0, time.UTC) consentValidDateTime.To = *plaid.NewNullableTime(&validUntil) constraints.SetValidDateTime(*consentValidDateTime) request := plaid.NewPaymentInitiationConsentCreateRequest( recipientID, "TestPaymentConsent", *constraints, ) request.SetType(plaid.PAYMENTINITIATIONCONSENTTYPE_COMMERCIAL); response, _, err := client.PlaidApi.PaymentInitiationConsentCreate(ctx).PaymentInitiationConsentCreateRequest(*request).Execute() consentID := response.GetConsentId() ``` ```bash curl -X POST https://sandbox.plaid.com/payment_initiation/consent/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "recipient_id": String, "reference": "TestPaymentConsent", "type": "COMMERCIAL", "constraints": { "valid_date_time": { "to": "2024-12-31T23:59:59Z" }, "max_payment_amount": {"currency": "GBP", "value": 15}, "periodic_amounts": [ {"amount": {"currency": "GBP", "value": 40}, "alignment": "CALENDAR", "interval": "MONTH"} ] } }' ``` ```ruby request = Plaid::PaymentInitiationConsentCreateRequest.new( { recipient_id: recipient_id, reference: 'TestPaymentConsent', type: 'COMMERCIAL', constraints: { valid_date_time: { to: '2024-12-31T23:59:59Z' }, max_payment_amount: {currency: 'GBP', value: 15}, "periodic_amounts": [ { amount: {currency: 'GBP', value: 40}, alignment: 'CALENDAR', interval: 'MONTH' } ] } } ) response = client.payment_initiation_consent_create(request) consent_id = response.consent_id ``` ```java PaymentConsentValidDateTime validDateTime = new PaymentConsentValidDateTime() .to(OffsetDateTime.of(2024, 12, 31, 23, 59, 59, 0, ZoneOffset.UTC)); PaymentConsentMaxPaymentAmount maxPaymentAmount = new PaymentConsentMaxPaymentAmount() .currency(PaymentAmountCurrency.GBP) .value(15.00); List periodicAmounts = Arrays.asList( new PaymentConsentPeriodicAmount() .amount(new PaymentConsentPeriodicAmountAmount().currency(PaymentAmountCurrency.GBP).value(40.00)) .alignment(PaymentConsentPeriodicAlignment.CALENDAR) .interval(PaymentConsentPeriodicInterval.MONTH) ); PaymentInitiationConsentConstraints constraints = new PaymentInitiationConsentConstraints() .validDateTime(validDateTime) .maxPaymentAmount(maxPaymentAmount) .periodicAmounts(periodicAmounts); PaymentInitiationConsentCreateRequest request = new PaymentInitiationConsentCreateRequest() .recipientId(recipientId) .reference("TestPaymentConsent") .type(PaymentInitiationConsentType.COMMERCIAL) .constraints(constraints); Response response = client .paymentInitiationConsentCreate(request) .execute(); ``` ```node const request: PaymentInitiationConsentCreateRequest = { recipient_id: recipientID, reference: 'TestPaymentConsent', type: PaymentInitiationConsentType.Commercial, constraints: { valid_date_time: { to: '2024-12-31T23:59:59Z', }, max_payment_amount: { currency: PaymentAmountCurrency.Gbp, value: 15, }, periodic_amounts: [ { amount: { currency: PaymentAmountCurrency.Gbp, value: 40, }, alignment: PaymentConsentPeriodicAlignment.Calendar, interval: PaymentConsentPeriodicInterval.Month, }, ], }, }; try { const response = await plaidClient.paymentInitiationConsentCreate(request); const consentID = response.data.consent_id; const status = response.data.status; } catch (error) { // handle error } ``` #### Response fields  string A unique ID identifying the payment consent. string The status of the payment consent. `UNAUTHORISED`: Consent created, but requires user authorisation. `REJECTED`: Consent authorisation was rejected by the bank. `AUTHORISED`: Consent is active and ready to be used. `REVOKED`: Consent has been revoked and can no longer be used. `EXPIRED`: Consent is no longer valid. Possible values: `UNAUTHORISED`, `AUTHORISED`, `REVOKED`, `REJECTED`, `EXPIRED` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "consent_id": "consent-id-production-feca8a7a-5491-4444-9999-f3062bb735d3", "status": "UNAUTHORISED", "request_id": "4ciYmmesdqSiUAB" } ``` \=\*=\*=\*= #### /payment\_initiation/consent/get  #### Get payment consent  The [/payment\_initiation/consent/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentget) endpoint can be used to check the status of a payment consent, as well as to receive basic information such as recipient and constraints. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The `consent_id` returned from `/payment_initiation/consent/create`. ```python request = PaymentInitiationConsentGetRequest(consent_id=consent_id) response = client.payment_initiation_consent_get(request) consent_id = response["consent_id"] status = response["status"] ``` ```go request := plaid.NewPaymentInitiationConsentGetRequest(consentID) response, _, err := client.PlaidApi.PaymentInitiationConsentGet(ctx).PaymentInitiationConsentGetRequest(*request).Execute() consentID := response.GetConsentId() status := response.GetStatus() ``` ```bash curl -X POST https://sandbox.plaid.com/payment_initiation/consent/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "consent_id": String }' ``` ```ruby request = Plaid::PaymentInitiationConsentGetRequest.new({ consent_id: consent_id }) response = client.payment_initiation_consent_get(request) consent_id = response.consent_id status = response.status ``` ```java PaymentInitiationConsentGetRequest request = new PaymentInitiationConsentGetRequest() .consentId(consentId); Response response = client .paymentInitiationConsentGet(request) .execute(); ``` ```node const request: PaymentInitiationConsentGetRequest = { consent_id: consentID, }; try { const response = await plaidClient.paymentInitiationConsentGet(request); const consentID = response.data.consent_id; const status = response.data.status; } catch (error) { // handle error } ``` #### Response fields  string The consent ID. Min length: `1` string The status of the payment consent. `UNAUTHORISED`: Consent created, but requires user authorisation. `REJECTED`: Consent authorisation was rejected by the bank. `AUTHORISED`: Consent is active and ready to be used. `REVOKED`: Consent has been revoked and can no longer be used. `EXPIRED`: Consent is no longer valid. Possible values: `UNAUTHORISED`, `AUTHORISED`, `REVOKED`, `REJECTED`, `EXPIRED` string Consent creation timestamp, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` string The ID of the recipient the payment consent is for. Min length: `1` string A reference for the payment consent. object Limitations that will be applied to payments initiated using the payment consent. nullable, object Life span for the payment consent. After the `to` date the payment consent expires and can no longer be used for payment initiation. nullable, string The date and time from which the consent should be active, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` nullable, string The date and time at which the consent expires, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` object Maximum amount of a single payment initiated using the payment consent. string The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: `GBP`, `EUR`, `PLN`, `SEK`, `DKK`, `NOK` Min length: `3` Max length: `3` number The amount of the payment. Must contain at most two digits of precision e.g. `1.23`. Minimum accepted value is `1`. Format: `double` \[object\] A list of amount limitations per period of time. Min items: `1` object Maximum cumulative amount for all payments in the specified interval. string The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: `GBP`, `EUR`, `PLN`, `SEK`, `DKK`, `NOK` Min length: `3` Max length: `3` number The amount of the payment. Must contain at most two digits of precision e.g. `1.23`. Minimum accepted value is `1`. Format: `double` string Payment consent periodic interval. Possible values: `DAY`, `WEEK`, `MONTH`, `YEAR` string Where the payment consent period should start. If the institution is Monzo, only `CONSENT` alignments are supported. `CALENDAR`: line up with a calendar. `CONSENT`: on the date of consent creation. Possible values: `CALENDAR`, `CONSENT` deprecated, \[string\] Deprecated, use the 'type' field instead. Possible values: `ME_TO_ME`, `EXTERNAL` string Payment consent type. Defines possible use case for payments made with the given consent. `SWEEPING`: Allows moving money between accounts owned by the same user. `COMMERCIAL`: Allows initiating payments from the user's account to third parties. Possible values: `SWEEPING`, `COMMERCIAL` nullable, object Details about external payment refund string The name of the account holder. nullable, string The International Bank Account Number (IBAN) for the account. nullable, object An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "4ciYuuesdqSiUAB", "consent_id": "consent-id-production-feca8a7a-5491-4aef-9298-f3062bb735d3", "status": "AUTHORISED", "created_at": "2021-10-30T15:26:48Z", "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6", "reference": "ref-00001", "constraints": { "valid_date_time": { "from": "2021-12-25T11:12:13Z", "to": "2022-12-31T15:26:48Z" }, "max_payment_amount": { "currency": "GBP", "value": 100 }, "periodic_amounts": [ { "amount": { "currency": "GBP", "value": 300 }, "interval": "WEEK", "alignment": "CALENDAR" } ] }, "type": "SWEEPING" } ``` \=\*=\*=\*= #### /payment\_initiation/consent/revoke  #### Revoke payment consent  The [/payment\_initiation/consent/revoke](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentrevoke) endpoint can be used to revoke the payment consent. Once the consent is revoked, it is not possible to initiate payments using it. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The consent ID. ```python request = PaymentInitiationConsentRevokeRequest(consent_id=consent_id) response = client.payment_initiation_consent_revoke(request) ``` ```go request := plaid.NewPaymentInitiationConsentRevokeRequest(consentID) response, _, err := client.PlaidApi.PaymentInitiationConsentRevoke(ctx).PaymentInitiationConsentRevokeRequest(*request).Execute() ``` ```bash curl -X POST https://sandbox.plaid.com/payment_initiation/consent/revoke \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "consent_id": String }' ``` ```ruby request = Plaid::PaymentInitiationConsentRevokeRequest.new({ consent_id: consent_id }) response = client.payment_initiation_consent_revoke(request) ``` ```java PaymentInitiationConsentRevokeRequest request = new PaymentInitiationConsentRevokeRequest() .consentId(consentId); Response response = client .paymentInitiationConsentRevoke(request) .execute(); ``` ```node const request: PaymentInitiationConsentRevokeRequest = { consent_id: consentID, }; try { const response = await plaidClient.paymentInitiationConsentRevoke(request); } catch (error) { // handle error } ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "4ciYaaesdqSiUAB" } ``` \=\*=\*=\*= #### /payment\_initiation/consent/payment/execute  #### Execute a single payment using consent  The [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) endpoint can be used to execute payments using payment consent. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The consent ID. required, object The amount and currency of a payment required, string The ISO-4217 currency code of the payment. For standing orders and payment consents, `"GBP"` must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported. Possible values: `GBP`, `EUR`, `PLN`, `SEK`, `DKK`, `NOK` Min length: `3` Max length: `3` required, number The amount of the payment. Must contain at most two digits of precision e.g. `1.23`. Minimum accepted value is `1`. Format: `double` required, string A random key provided by the client, per unique consent payment. Maximum of 128 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a consent payment fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single payment is created. If the request was successfully processed, it will prevent any payment that uses the same idempotency key, and was received within 48 hours of the first request, from being processed. Max length: `128` Min length: `1` string A reference for the payment. This must be an alphanumeric string with at most 18 characters and must not contain any special characters (since not all institutions support them). If not provided, Plaid will automatically fall back to the reference from consent. In order to track settlement via Payment Confirmation, each payment must have a unique reference. If the reference provided through the API is not unique, Plaid will adjust it. Some institutions may limit the reference to less than 18 characters. If necessary, Plaid will adjust the reference by truncating it to fit the institution's requirements. Both the originally provided and automatically adjusted references (if any) can be found in the `reference` and `adjusted_reference` fields, respectively. Min length: `1` Max length: `18` deprecated, string Deprecated, payments will be executed within the type of the consent. A scope of the payment. Must be one of the scopes mentioned in the consent. Optional if the appropriate consent has only one scope defined, required otherwise. Possible values: `ME_TO_ME`, `EXTERNAL` string Decides the mode under which the payment processing should be performed, using `IMMEDIATE` as default. `IMMEDIATE`: Will immediately execute the payment, waiting for a response from the ASPSP before returning the result of the payment initiation. This is ideal for user-present flows. `ASYNC`: Will accept a payment execution request and schedule it for processing, immediately returning the new `payment_id`. Listen for webhooks to obtain real-time updates on the payment status. This is ideal for non user-present flows. Possible values: `ASYNC`, `IMMEDIATE` ```python request = PaymentInitiationConsentPaymentExecuteRequest( consent_id=consent_id, amount=PaymentAmount(currency="GBP",value=7.99), idempotency_key=idempotency_key, reference="Payment1" ) response = client.payment_initiation_consent_payment_execute(request) payment_id = response["payment_id"] status = response["status"] ``` ```go request := plaid.NewPaymentInitiationConsentPaymentExecuteRequest(consentID, *plaid.NewPaymentAmount("GBP", 7.99), idempotencyKey) request.SetReference("Payment1") response, _, err := client.PlaidApi.PaymentInitiationConsentPaymentExecute(ctx).PaymentInitiationConsentPaymentExecuteRequest(*request).Execute() paymentID := response.GetPaymentId() status := response.GetStatus() ``` ```bash curl -X POST https://sandbox.plaid.com/payment_initiation/consent/payment/execute \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "consent_id": String, "idempotency_key": String, "amount": {"currency": "GBP", "value": 7.99}, "reference": "Payment1" }' ``` ```ruby request = Plaid::PaymentInitiationConsentPaymentExecuteRequest.new( { consent_id: consent_id, amount: {currency: 'GBP', value: 7.99}, idempotency_key: idempotency_key, reference: 'Payment1' } ) response = client.payment_initiation_consent_payment_execute(request) payment_id = response.payment_id status = response.status ``` ```java PaymentInitiationConsentPaymentExecuteRequest request = new PaymentInitiationConsentPaymentExecuteRequest() .consentId(consentId) .amount(new PaymentAmount().currency(PaymentAmountCurrency.GBP).value(7.99)) .reference("Payment1") .idempotencyKey(idempotencyKey); Response response = client .paymentInitiationConsentPaymentExecute(request) .execute(); ``` ```node const request: PaymentInitiationConsentPaymentExecuteRequest = { consent_id: consentID, amount: { currency: PaymentAmountCurrency.Gbp, value: 7.99, }, reference: 'Payment1', idempotency_key: idempotencyKey, }; try { const response = await plaidClient.paymentInitiationConsentPaymentExecute( request, ); const paymentID = response.data.payment_id; const status = response.data.status; } catch (error) { // handle error } ``` #### Response fields  string A unique ID identifying the payment string The status of the payment. Core lifecycle statuses: **`PAYMENT_STATUS_INPUT_NEEDED`**: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. **`PAYMENT_STATUS_AUTHORISING`:** Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. **`PAYMENT_STATUS_INITIATED`:** The payment has been authorised and accepted by the financial institution. In many EU markets, `PAYMENT_STATUS_EXECUTED` is not supported, and a payment will remain in `PAYMENT_STATUS_INITIATED` until the funds settle, making this a terminal success state in those cases. A payment in `PAYMENT_STATUS_INITIATED` should be treated as a successfully submitted payment; do not gate downstream processing on reaching `PAYMENT_STATUS_EXECUTED`. For a full explanation of payment statuses and how to handle each, see the [Payment Status guide](https://plaid.com/docs/payment-initiation/payment-status/index.html.md) . **`PAYMENT_STATUS_EXECUTED`: Terminal.** The funds have left the payer’s account and the payment is en route to settlement. Note that this status does not confirm that funds have arrived in the recipient’s account; do not use it as proof of fund receipt. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in `PAYMENT_STATUS_INITIATED` before settling. When using Plaid Virtual Accounts, `PAYMENT_STATUS_EXECUTED` is not terminal—the payment will continue to `PAYMENT_STATUS_SETTLED` once funds are available. **`PAYMENT_STATUS_SETTLED`: Terminal.** The funds are available in the recipient’s account. Only available to customers using [Plaid Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) . Failure statuses: **`PAYMENT_STATUS_INSUFFICIENT_FUNDS`: Terminal.** The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. **`PAYMENT_STATUS_FAILED`: Terminal (retryable).** The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. **`PAYMENT_STATUS_BLOCKED`: Terminal (retryable).** The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. **`PAYMENT_STATUS_REJECTED`: Terminal.** The payment was rejected by the financial institution. No automatic retry is possible. **`PAYMENT_STATUS_CANCELLED`: Terminal.** The end user cancelled the payment during authorisation. Standing-order statuses: **`PAYMENT_STATUS_ESTABLISHED`: Terminal.** A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): `PAYMENT_STATUS_UNKNOWN`: The payment status is unknown. `PAYMENT_STATUS_PROCESSING`: The payment is currently being processed. `PAYMENT_STATUS_COMPLETED`: Indicates that the standing order has been successfully established. Possible values: `PAYMENT_STATUS_INPUT_NEEDED`, `PAYMENT_STATUS_PROCESSING`, `PAYMENT_STATUS_INITIATED`, `PAYMENT_STATUS_COMPLETED`, `PAYMENT_STATUS_INSUFFICIENT_FUNDS`, `PAYMENT_STATUS_FAILED`, `PAYMENT_STATUS_BLOCKED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_STATUS_EXECUTED`, `PAYMENT_STATUS_SETTLED`, `PAYMENT_STATUS_AUTHORISING`, `PAYMENT_STATUS_CANCELLED`, `PAYMENT_STATUS_ESTABLISHED`, `PAYMENT_STATUS_REJECTED` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. Response Object ```json { "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3", "request_id": "4ciYccesdqSiUAB", "status": "PAYMENT_STATUS_INITIATED" } ``` ### Webhooks  Updates are sent to indicate that the status of an initiated payment has changed. All Payment Initiation webhooks have a `webhook_type` of `PAYMENT_INITIATION`. \=\*=\*=\*= #### PAYMENT\_STATUS\_UPDATE  Fired when the status of a payment has changed. For a full explanation of payment statuses and how to handle each, see the [Payment Status guide](https://plaid.com/docs/payment-initiation/payment-status/index.html.md) . Note: Plaid payment statuses do not constitute proof that funds have arrived in the recipient's account. Do not use `new_payment_status` to confirm fund settlement. #### Properties  string `PAYMENT_INITIATION` string `PAYMENT_STATUS_UPDATE` string The `payment_id` for the payment being updated string The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts. string The status of the payment. Core lifecycle statuses: **`PAYMENT_STATUS_INPUT_NEEDED`**: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. **`PAYMENT_STATUS_AUTHORISING`:** Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. **`PAYMENT_STATUS_INITIATED`:** The payment has been authorised and accepted by the financial institution. In many EU markets, `PAYMENT_STATUS_EXECUTED` is not supported, and a payment will remain in `PAYMENT_STATUS_INITIATED` until the funds settle, making this a terminal success state in those cases. A payment in `PAYMENT_STATUS_INITIATED` should be treated as a successfully submitted payment; do not gate downstream processing on reaching `PAYMENT_STATUS_EXECUTED`. For a full explanation of payment statuses and how to handle each, see the [Payment Status guide](https://plaid.com/docs/payment-initiation/payment-status/index.html.md) . **`PAYMENT_STATUS_EXECUTED`: Terminal.** The funds have left the payer’s account and the payment is en route to settlement. Note that this status does not confirm that funds have arrived in the recipient’s account; do not use it as proof of fund receipt. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in `PAYMENT_STATUS_INITIATED` before settling. When using Plaid Virtual Accounts, `PAYMENT_STATUS_EXECUTED` is not terminal—the payment will continue to `PAYMENT_STATUS_SETTLED` once funds are available. **`PAYMENT_STATUS_SETTLED`: Terminal.** The funds are available in the recipient’s account. Only available to customers using [Plaid Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) . Failure statuses: **`PAYMENT_STATUS_INSUFFICIENT_FUNDS`: Terminal.** The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. **`PAYMENT_STATUS_FAILED`: Terminal (retryable).** The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. **`PAYMENT_STATUS_BLOCKED`: Terminal (retryable).** The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. **`PAYMENT_STATUS_REJECTED`: Terminal.** The payment was rejected by the financial institution. No automatic retry is possible. **`PAYMENT_STATUS_CANCELLED`: Terminal.** The end user cancelled the payment during authorisation. Standing-order statuses: **`PAYMENT_STATUS_ESTABLISHED`: Terminal.** A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): `PAYMENT_STATUS_UNKNOWN`: The payment status is unknown. `PAYMENT_STATUS_PROCESSING`: The payment is currently being processed. `PAYMENT_STATUS_COMPLETED`: Indicates that the standing order has been successfully established. Possible values: `PAYMENT_STATUS_INPUT_NEEDED`, `PAYMENT_STATUS_PROCESSING`, `PAYMENT_STATUS_INITIATED`, `PAYMENT_STATUS_COMPLETED`, `PAYMENT_STATUS_INSUFFICIENT_FUNDS`, `PAYMENT_STATUS_FAILED`, `PAYMENT_STATUS_BLOCKED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_STATUS_EXECUTED`, `PAYMENT_STATUS_SETTLED`, `PAYMENT_STATUS_AUTHORISING`, `PAYMENT_STATUS_CANCELLED`, `PAYMENT_STATUS_ESTABLISHED`, `PAYMENT_STATUS_REJECTED` string The status of the payment. Core lifecycle statuses: **`PAYMENT_STATUS_INPUT_NEEDED`**: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. **`PAYMENT_STATUS_AUTHORISING`:** Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. **`PAYMENT_STATUS_INITIATED`:** The payment has been authorised and accepted by the financial institution. In many EU markets, `PAYMENT_STATUS_EXECUTED` is not supported, and a payment will remain in `PAYMENT_STATUS_INITIATED` until the funds settle, making this a terminal success state in those cases. A payment in `PAYMENT_STATUS_INITIATED` should be treated as a successfully submitted payment; do not gate downstream processing on reaching `PAYMENT_STATUS_EXECUTED`. For a full explanation of payment statuses and how to handle each, see the [Payment Status guide](https://plaid.com/docs/payment-initiation/payment-status/index.html.md) . **`PAYMENT_STATUS_EXECUTED`: Terminal.** The funds have left the payer’s account and the payment is en route to settlement. Note that this status does not confirm that funds have arrived in the recipient’s account; do not use it as proof of fund receipt. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in `PAYMENT_STATUS_INITIATED` before settling. When using Plaid Virtual Accounts, `PAYMENT_STATUS_EXECUTED` is not terminal—the payment will continue to `PAYMENT_STATUS_SETTLED` once funds are available. **`PAYMENT_STATUS_SETTLED`: Terminal.** The funds are available in the recipient’s account. Only available to customers using [Plaid Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) . Failure statuses: **`PAYMENT_STATUS_INSUFFICIENT_FUNDS`: Terminal.** The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. **`PAYMENT_STATUS_FAILED`: Terminal (retryable).** The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. **`PAYMENT_STATUS_BLOCKED`: Terminal (retryable).** The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. **`PAYMENT_STATUS_REJECTED`: Terminal.** The payment was rejected by the financial institution. No automatic retry is possible. **`PAYMENT_STATUS_CANCELLED`: Terminal.** The end user cancelled the payment during authorisation. Standing-order statuses: **`PAYMENT_STATUS_ESTABLISHED`: Terminal.** A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): `PAYMENT_STATUS_UNKNOWN`: The payment status is unknown. `PAYMENT_STATUS_PROCESSING`: The payment is currently being processed. `PAYMENT_STATUS_COMPLETED`: Indicates that the standing order has been successfully established. Possible values: `PAYMENT_STATUS_INPUT_NEEDED`, `PAYMENT_STATUS_PROCESSING`, `PAYMENT_STATUS_INITIATED`, `PAYMENT_STATUS_COMPLETED`, `PAYMENT_STATUS_INSUFFICIENT_FUNDS`, `PAYMENT_STATUS_FAILED`, `PAYMENT_STATUS_BLOCKED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_STATUS_EXECUTED`, `PAYMENT_STATUS_SETTLED`, `PAYMENT_STATUS_AUTHORISING`, `PAYMENT_STATUS_CANCELLED`, `PAYMENT_STATUS_ESTABLISHED`, `PAYMENT_STATUS_REJECTED` string The original value of the reference when creating the payment. string The value of the reference sent to the bank after adjustment to pass bank validation rules. string The original value of the `start_date` provided during the creation of a standing order. If the payment is not a standing order, this field will be `null`. Format: `date` string The start date sent to the bank after adjusting for holidays or weekends. Will be provided in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). If the start date did not require adjustment, or if the payment is not a standing order, this field will be `null`. Format: `date` string The timestamp of the update, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2017-09-14T14:42:19.350Z"` Format: `date-time` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "PAYMENT_INITIATION", "webhook_code": "PAYMENT_STATUS_UPDATE", "payment_id": "payment-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2", "new_payment_status": "PAYMENT_STATUS_INITIATED", "old_payment_status": "PAYMENT_STATUS_PROCESSING", "original_reference": "Account Funding 99744", "adjusted_reference": "Account Funding 99", "original_start_date": "2017-09-14", "adjusted_start_date": "2017-09-15", "timestamp": "2017-09-14T14:42:19.350Z", "environment": "production" } ``` \=\*=\*=\*= #### CONSENT\_STATUS\_UPDATE  Fired when the status of a payment consent has changed. #### Properties  string `PAYMENT_INITIATION` string `CONSENT_STATUS_UPDATE` string The `id` for the consent being updated string The status of the payment consent. `UNAUTHORISED`: Consent created, but requires user authorisation. `REJECTED`: Consent authorisation was rejected by the bank. `AUTHORISED`: Consent is active and ready to be used. `REVOKED`: Consent has been revoked and can no longer be used. `EXPIRED`: Consent is no longer valid. Possible values: `UNAUTHORISED`, `AUTHORISED`, `REVOKED`, `REJECTED`, `EXPIRED` string The status of the payment consent. `UNAUTHORISED`: Consent created, but requires user authorisation. `REJECTED`: Consent authorisation was rejected by the bank. `AUTHORISED`: Consent is active and ready to be used. `REVOKED`: Consent has been revoked and can no longer be used. `EXPIRED`: Consent is no longer valid. Possible values: `UNAUTHORISED`, `AUTHORISED`, `REVOKED`, `REJECTED`, `EXPIRED` string The timestamp of the update, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2017-09-14T14:42:19.350Z"` Format: `date-time` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "PAYMENT_INITIATION", "webhook_code": "CONSENT_STATUS_UPDATE", "consent_id": "payment-consent-id-production-e7258765-69f9-46b1-9c67-d2800448e5ff", "old_status": "UNAUTHORISED", "new_status": "AUTHORISED", "timestamp": "2017-09-14T14:42:19.350Z", "environment": "production" } ``` --- # API - Protect | Plaid Docs #### This page is not available  ##### Log in to view this page   Protect docs are currently available only to members of the Protect beta program. To request access, [join the waitlist](https://plaid.com/products/protect/#contact-form) . If you think you're seeing this message in error, make sure to [log in to your Dashboard account](https://dashboard.plaid.com) , or contact your account manager. --- # API - Signal and Balance | Plaid Docs Signal Transaction Scores and Balance endpoints  ================================================ #### API Reference guide for the Signal Transaction Scores and Balance products  For how-to guidance, see the [Balance documentation](https://plaid.com/docs/balance/index.html.md) and [Signal Transaction Scores documentation](https://plaid.com/docs/signal/index.html.md) . | Plaid Signal endpoints (for both Balance and Signal Transaction Scores) | | | --- | --- | | [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) | Evaluate a proposed ACH transaction for return risk | | [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) | Report whether you initiated an ACH transaction | | [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) | Report a return for an ACH transaction | | Signal Transaction Scores-only endpoints | | | --- | --- | | [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) | Enable an existing Item for Signal Transaction Scores | | Balance-only endpoints | | | --- | --- | | [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) | Fetch real-time balances | | See also | | | --- | --- | | [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) | Create a token for using Plaid Signal Transaction Scores with a processor partner | | [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) | Evaluate a proposed ACH transaction for return risk as a processor partner | | [/processor/signal/decision/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignaldecisionreport) | Report whether you initiated an ACH transaction as a processor partner | | [/processor/signal/return/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalreturnreport) | Report a return for an ACH transaction as a processor partner | | [/processor/signal/prepare](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalprepare) | Enable an existing processor token for Signal Transaction Scores | | [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) | Fetch real-time balances as a processor partner | \=\*=\*=\*= #### /signal/evaluate  #### Evaluate a planned ACH transaction  Use [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) to evaluate a planned ACH transaction to get a return risk assessment and additional risk signals. Before using [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , you must first [create a ruleset](https://plaid.com/docs/signal/signal-rules/index.html.md) in the Dashboard under [Signal->Rules](https://dashboard.plaid.com/signal/risk-profiles) . [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) can be used with either Signal Transaction Scores or the Balance product. Which product is used will be determined by the `ruleset_key` that you provide. For more details, see [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) . Note: This request may have higher latency when using a Balance-only ruleset. This is because Plaid must communicate directly with the institution to request data. Balance-only rulesets may have latency of up to 30 seconds or more; if you encounter errors, you may find it necessary to adjust your timeout period when making requests. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. required, string The Plaid `account_id` of the account that is the funding source for the proposed transaction. The `account_id` is returned in the `/accounts/get` endpoint as well as the [onSuccess](https://plaid.com/docs/link/ios/index.html.md#link-ios-onsuccess-linkSuccess-metadata-accounts-id) callback metadata. This will return an [INVALID\_ACCOUNT\_ID](https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_account_id) error if the account has been removed at the bank or if the `account_id` is no longer valid. required, string The unique ID that you would like to use to refer to this evaluation attempt - for example, a payment attempt ID. You will use this later to debug this evaluation, and/or report an ACH return, etc. The max length for this field is 36 characters. Min length: `1` Max length: `36` required, number The transaction amount, in USD (e.g. `102.05`) Format: `double` string A unique ID that identifies the end user in your system. This ID is used to correlate requests by a user with multiple Items. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. boolean Use `true` if the ACH transaction is a part of recurring schedule (for example, a monthly repayment); `false` otherwise. When using a Balance-only ruleset, this field is ignored. string The default ACH payment method to complete the transaction. When using a Balance-only ruleset, this field is ignored. `SAME_DAY_ACH`: Same Day ACH by Nacha. The debit transaction is processed and settled on the same day. `STANDARD_ACH`: Standard ACH by Nacha. `MULTIPLE_PAYMENT_METHODS`: If there is no default debit rail or there are multiple payment methods. Possible values: `SAME_DAY_ACH`, `STANDARD_ACH`, `MULTIPLE_PAYMENT_METHODS` object Details about the end user initiating the transaction (i.e., the account holder). These fields are optional, but strongly recommended to increase the accuracy of results when using Signal Transaction Scores. When using a Balance-only ruleset, if the Signal Addendum has been signed, these fields are ignored; if the Addendum has not been signed, using these fields will result in an error. object The user's legal name string The user's name prefix (e.g. "Mr.") string The user's given name. If the user has a one-word name, it should be provided in this field. string The user's middle name string The user's family name / surname string The user's name suffix (e.g. "II") string The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567" string The user's email address. object Data about the components comprising an address. string The full city name string The region or state Example: `"NC"` string The full street address Example: `"564 Main Street, APT 15"` string The postal code string The ISO 3166-1 alpha-2 country code object Details about the end user's device. These fields are optional, but strongly recommended to increase the accuracy of results when using Signal Transaction Scores. When using a Balance-only Ruleset, these fields are ignored if the Signal Addendum has been signed; if it has not been signed, using these fields will result in an error. string The IP address of the device that initiated the transaction string The user agent of the device that initiated the transaction (e.g. "Mozilla/5.0") string The key of the ruleset to use for evaluating this transaction. You can create a ruleset using the Plaid Dashboard, under [Signal->Rules](https://dashboard.plaid.com/signal/risk-profiles) . If not provided, for all new customers as of October 15, 2025, the `default` ruleset will be used. For existing Signal Transaction Scores customers as of October 15, 2025, by default, no ruleset will be used if the `ruleset_key` is not provided. For more information, or to opt out of using rulesets, see [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) . ```node const eval_request = { access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', client_transaction_id: 'txn12345', amount: 123.45, client_user_id: 'user1234', user: { name: { prefix: 'Ms.', given_name: 'Jane', middle_name: 'Leah', family_name: 'Doe', suffix: 'Jr.', }, phone_number: '+14152223333', email_address: 'jane.doe@example.com', address: { street: '2493 Leisure Lane', city: 'San Matias', region: 'CA', postal_code: '93405-2255', country: 'US', }, }, device: { ip_address: '198.30.2.2', user_agent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1', }, }; try { const eval_response = await plaidClient.signalEvaluate(eval_request); const core_attributes = eval_response.data.core_attributes; const scores = eval_response.data.scores; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/signal/evaluate \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "client_transaction_id": "txn12345", "amount": 123.45, "ruleset_key": "normal_risk" } ``` ```ruby request = Plaid::SignalEvaluateRequest.new( { access_token: access_token, account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', client_transaction_id: 'txn12345', amount: 123.45, ruleset_key: "normal_risk" } ) response = client.signal_evaluate(request) result = response.ruleset.result ``` ```java SignalEvaluateRequest request = new SignalEvaluateRequest() .accessToken("access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175") .accountId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr") .clientTransactionId("txn12345") .amount(123.45) .rulesetKey("normal_risk"); Response response = plaidClient() .signalEvaluate(request) .execute(); RuleResult result = response.body().getRuleset().getResult(); ``` ```python request = SignalEvaluateRequest( access_token="access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", account_id="3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", client_transaction_id="txn123", amount=123.45, ruleset_key="normal_risk" ) response = client.signal_evaluate(request) result = response['ruleset']['result'] ``` ```go request := plaid.NewSignalEvaluateRequest( "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "txn12345", 123.45, ) request.SetRulesetKey("normal_risk") response, _, err := client.PlaidApi.SignalEvaluate(ctx).SignalEvaluateRequest(*request).Execute() result := response.GetRuleset().GetResult() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. nullable, object Risk scoring details broken down by risk category. When using a Balance-only ruleset, this object will not be returned. object The object contains a risk score and a risk tier that evaluate the transaction return risk of an unauthorized debit. Common return codes in this category include: "R05", "R07", "R10", "R11", "R29". These returns typically have a return time frame of up to 60 calendar days. During this period, the customer of financial institutions can dispute a transaction as unauthorized. integer A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood. Minimum: `1` Maximum: `99` object The object contains a risk score and a risk tier that evaluate the transaction return risk because an account is overdrawn or because an ineligible account is used. Common return codes in this category include: "R01", "R02", "R03", "R04", "R06", "R08", "R09", "R13", "R16", "R17", "R20", "R23". These returns have a turnaround time of 2 banking days. integer A score from 1-99 that indicates the transaction return risk: a higher risk score suggests a higher return likelihood. Minimum: `1` Maximum: `99` object The core attributes object contains additional data that can be used to assess the ACH return risk. If using a Balance-only ruleset, only `available_balance` and `current_balance` will be returned as core attributes. If using a Signal Transaction Scores ruleset, over 80 core attributes will be returned. Examples of attributes include: `available_balance` and `current_balance`: The balance in the ACH transaction funding account `days_since_first_plaid_connection`: The number of days since the first time the Item was connected to an application via Plaid `plaid_connections_count_7d`: The number of times the Item has been connected to applications via Plaid over the past 7 days `plaid_connections_count_30d`: The number of times the Item has been connected to applications via Plaid over the past 30 days `total_plaid_connections_count`: The number of times the Item has been connected to applications via Plaid `is_savings_or_money_market_account`: Indicates whether the ACH transaction funding account is a savings/money market account For the full list and detailed documentation of core attributes available, or to request that core attributes not be returned, contact Sales or your Plaid account manager. nullable, object Details about the transaction result after evaluation by the requested Ruleset. If a `ruleset_key` is not provided, for customers who began using Signal Transaction Scores before October 15, 2025, by default, this field will be omitted. To learn more, see [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) . string The key of the Ruleset used for this transaction. string The result of the rule that was triggered for this transaction. `ACCEPT`: Accept the transaction for processing. `REROUTE`: Reroute the transaction to a different payment method, as this transaction is too risky. `REVIEW`: Review the transaction before proceeding. Possible values: `ACCEPT`, `REROUTE`, `REVIEW` nullable, object Rules are run in numerical order. The first rule with a logic match is triggered. These are the details of that rule. string An optional message attached to the triggered rule, defined within the Dashboard, for your internal use. Useful for debugging, such as “Account appears to be closed.” string A string key, defined within the Dashboard, used to trigger programmatic behavior for a certain result. For instance, you could optionally choose to define a "3-day-hold" `custom_action_key` for an ACCEPT result. \[object\] If bank information was not available to be used in the Signal Transaction Scores model, this array contains warnings describing why bank data is missing. If you want to receive an API error instead of results in the case of missing bank data, file a support ticket or contact your Plaid account manager. string A broad categorization of the warning. Safe for programmatic use. string The warning code identifies a specific kind of warning that pertains to the error causing bank data to be missing. Safe for programmatic use. For more details on warning codes, please refer to Plaid standard error codes documentation. If you receive the `ITEM_LOGIN_REQUIRED` warning, we recommend re-authenticating your user by implementing Link's update mode. This will guide your user to fix their credentials, allowing Plaid to start fetching data again for future requests. string A developer-friendly representation of the warning type. This may change over time and is not safe for programmatic use. Response Object ```json { "scores": { "customer_initiated_return_risk": { "score": 9 }, "bank_initiated_return_risk": { "score": 82 } }, "core_attributes": { "available_balance": 2200, "current_balance": 2000 }, "ruleset": { "ruleset_key": "onboarding_flow", "result": "REROUTE", "triggered_rule_details": { "internal_note": "Rerouting customer to different payment method, since bank risk score is too high" } }, "warnings": [], "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /signal/decision/report  #### Report whether you initiated an ACH transaction  After you call [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , Plaid will normally infer the outcome from your Signal Rules. However, if you are not using Signal Rules, if the Signal Rules outcome was `REVIEW`, or if you take a different action than the one determined by the Signal Rules, you will need to call [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) . This helps improve Signal Transaction Score accuracy for your account and is necessary for proper functioning of the rule performance and rule tuning capabilities in the Dashboard. If your effective decision changes after calling [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) (for example, you indicated that you accepted a transaction, but later on, your payment processor rejected it, so it was never initiated), call [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) again for the transaction to correct Plaid's records. If you are using Plaid Transfer as your payment processor, you also do not need to call [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) , as Plaid can infer outcomes from your Transfer activity. If using a Balance-only ruleset, this endpoint will not impact scores (Balance does not use scores), but is necessary to view accurate transaction outcomes and tune rule logic in the Dashboard. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Must be the same as the `client_transaction_id` supplied when calling `/signal/evaluate` Min length: `1` Max length: `36` required, boolean `true` if the ACH transaction was initiated, `false` otherwise. This field must be returned as a boolean. If formatted incorrectly, this will result in an [INVALID\_FIELD](https://plaid.com/docs/errors/invalid-request/index.html.md#invalid_field) error. integer The actual number of days (hold time) since the ACH debit transaction that you wait before making funds available to your customers. The holding time could affect the ACH return rate. For example, use 0 if you make funds available to your customers instantly or the same day following the debit transaction, or 1 if you make funds available the next day following the debit initialization. Minimum: `0` string The payment decision from the risk assessment. `APPROVE`: approve the transaction without requiring further actions from your customers. For example, use this field if you are placing a standard hold for all the approved transactions before making funds available to your customers. You should also use this field if you decide to accelerate the fund availability for your customers. `REVIEW`: the transaction requires manual review `REJECT`: reject the transaction `TAKE_OTHER_RISK_MEASURES`: for example, placing a longer hold on funds than those approved transactions or introducing customer frictions such as step-up verification/authentication `NOT_EVALUATED`: if only logging the results without using them Possible values: `APPROVE`, `REVIEW`, `REJECT`, `TAKE_OTHER_RISK_MEASURES`, `NOT_EVALUATED` string The payment method to complete the transaction after the risk assessment. It may be different from the default payment method. `SAME_DAY_ACH`: Same Day ACH by Nacha. The debit transaction is processed and settled on the same day. `STANDARD_ACH`: Standard ACH by Nacha. `MULTIPLE_PAYMENT_METHODS`: if there is no default debit rail or there are multiple payment methods. Possible values: `SAME_DAY_ACH`, `STANDARD_ACH`, `MULTIPLE_PAYMENT_METHODS` number The amount (in USD) made available to your customers instantly following the debit transaction. It could be a partial amount of the requested transaction (example: 102.05). Format: `double` ```node const decision_report_request = { client_transaction_id: 'txn12345', initiated: true, days_funds_on_hold: 3, }; try { const decision_report_response = await plaidClient.signalDecisionReport( decision_report_request, ); const decision_request_id = decision_report_response.data.request_id; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/signal/decision/report \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_transaction_id": "txn123", "initiated": true }' ``` ```ruby request = Plaid::SignalDecisionReportRequest.new( { client_transaction_id: 'txn12345', initiated: true, days_funds_on_hold: 3 } ) response = client.signal_decision_report(request) request_id = response.request_id ``` ```java SignalDecisionReportRequest request = new SignalDecisionReportRequest() .clientTransactionId("txn12345") .initiated(true) .daysFundsOnHold(3); Response response = plaidClient() .signalDecisionReport(request) .execute(); String requestID = response.body().getRequestId(); ``` ```python request = SignalDecisionReportRequest( client_transaction_id="txn12345", initiated=True, days_funds_on_hold=3, ) response = client.signal_decision_report(request) request_id = response['request_id'] ``` ```go request := plaid.NewSignalDecisionReportRequest( "txn12345", true, ) request.SetDaysFundsOnHold(3) response, _, err := client.PlaidApi.SignalDecisionReport(ctx).SignalDecisionReportRequest(*request).Execute() request_id := response.GetRequestId() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /signal/return/report  #### Report a return for an ACH transaction  Call the [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) endpoint to report a returned transaction that was previously sent to the [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) endpoint. Your feedback will be used by the model to incorporate the latest risk trends into your scores and tune rule logic. If using a Balance-only ruleset, this endpoint will not impact scores (as Balance does not use scores), but is necessary to view accurate transaction outcomes and tune rule logic in the Dashboard. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Must be the same as the `client_transaction_id` supplied when calling `/signal/evaluate` or `/accounts/balance/get`. Min length: `1` Max length: `36` required, string Must be a valid ACH return code (e.g. "R01") If formatted incorrectly, this will result in an [INVALID\_FIELD](https://plaid.com/docs/errors/invalid-request/index.html.md#invalid_field) error. string Date and time when you receive the returns from your payment processors, in ISO 8601 format (`YYYY-MM-DDTHH:mm:ssZ`). Format: `date-time` ```node const return_report_request = { client_transaction_id: 'txn12345', return_code: 'R01', }; try { const return_report_response = await plaidClient.signalReturnReport( return_report_request, ); const request_id = return_report_response.data.request_id; console.log(request_id); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/signal/return/report \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_transaction_id": "txn12345", "return_code": "R01" }' ``` ```ruby request = Plaid::SignalReturnReportRequest.new( { client_transaction_id: 'txn12345', return_code: 'R01' } ) response = client.signal_return_report(request) request_id = response.request_id ``` ```java SignalReturnReportRequest request = new SignalReturnReportRequest() .clientTransactionId("txn12345") .returnCode("R01"); Response response = client() .signalReturnReport(request) .execute(); String requestId = response.body().getRequestId(); ``` ```python request = SignalReturnReportRequest( client_transaction_id="txn12345", return_code="R01", ) response = client.signal_return_report(request) request_id = response['request_id'] ``` ```go request := plaid.NewSignalReturnReportRequest( "txn12345", "R01", ) response, _, err := client.PlaidApi.SignalReturnReport(ctx).SignalReturnReportRequest(*request).Execute() request_id := response.GetRequestId() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /signal/prepare  #### Opt-in an Item to Signal Transaction Scores  When an Item is not initialized with `signal`, call [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) to opt-in that Item to the data collection process used to develop a Signal Transaction Score. This should be done on Items where `signal` was added in the `additional_consented_products` array but not in the `products`, `optional_products`, or `required_if_supported_products` array. If [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) is skipped on an Item that is not initialized with `signal`, the initial call to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) on that Item will be less accurate, because Plaid will have access to less data for computing the Signal Transaction Score. If your integration is purely Balance-only, this endpoint will have no effect, as Balance-only rulesets do not calculate a Signal Transaction Score. If run on an Item that is already initialized with `signal`, this endpoint will return a 200 response and will not modify the Item. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. ```node const prepare_request = { client_id: '7f57eb3d2a9j6480121fx361', secret: '79g03eoofwl8240v776r2h667442119', access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', }; try { const prepare_response = await plaidClient.signalPrepare(prepare_request); const request_id = prepare_response.data.request_id; console.log(request_id); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/signal/prepare \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175" }' ``` ```ruby request = Plaid::SignalPrepareRequest.new( { client_id: '7f57eb3d2a9j6480121fx361', secret: '79g03eoofwl8240v776r2h667442119', access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175' } ) response = client.signal_prepare(request) request_id = response.request_id ``` ```java SignalPrepareRequest request = new SignalPrepareRequest() .clientId("7f57eb3d2a9j6480121fx361") .secret("79g03eoofwl8240v776r2h667442119") .accessToken("access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175"); Response response = client() .signalPrepare(request) .execute(); String requestId = response.body().getRequestId(); ``` ```python request = SignalPrepareRequest( client_id="7f57eb3d2a9j6480121fx361", secret="79g03eoofwl8240v776r2h667442119", access_token="access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", ) response = client.signal_prepare(request) request_id = response['request_id'] ``` ```go request := plaid.NewSignalPrepareRequest( "7f57eb3d2a9j6480121fx361", "79g03eoofwl8240v776r2h667442119", "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", ) response, _, err := client.PlaidApi.SignalPrepare(ctx).SignalPrepareRequest(*request).Execute() request_id := response.GetRequestId() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /accounts/balance/get  #### Retrieve real-time balance data  The [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) endpoint returns the real-time balance for each of an Item's accounts. While other endpoints, such as [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) , return a balance object, [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) forces the available and current balance fields to be refreshed rather than cached. This endpoint can be used for existing Items that were added via any of Plaid’s other products. This endpoint can be used as long as Link has been initialized with any other product, `balance` itself is not a product that can be used to initialize Link. As this endpoint triggers a synchronous request for fresh data, latency may be higher than for other Plaid endpoints (typically less than 10 seconds, but occasionally up to 30 seconds or more); if you encounter errors, you may find it necessary to adjust your timeout period when making requests. Note: If you are getting real-time balance for the purpose of assessing the return risk of a proposed ACH transaction, it is recommended to use [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) instead of [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) . [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) returns the same real-time balance information and also provides access to Signal Rules, which provides no-code transaction business logic configuration, backtesting and recommendations for tuning your transaction acceptance logic, and the ability to easily switch between Balance and Signal Transaction Scores as needed for ultra-low-latency, ML-powered risk assessments. For more details, see the [Balance documentation](https://plaid.com/docs/balance/index.html.md#balance-integration-options) . #### Request fields  required, string The access token associated with the Item data is being requested for. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. object Optional parameters to `/accounts/balance/get`. \[string\] A list of `account_ids` to retrieve for the Item. The default value is `null`. Note: An error will be returned if a provided `account_id` is not associated with the Item. string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the oldest acceptable balance when making a request to `/accounts/balance/get`. This field is only necessary when the institution is `ins_128026` (Capital One), _and_ one or more account types being requested is a non-depository account (such as a credit card) as Capital One does not provide real-time balance for non-depository accounts. In this case, a value must be provided or an `INVALID_REQUEST` error with the code of `INVALID_FIELD` will be returned. For all other institutions, as well as for depository accounts at Capital One (including all checking and savings accounts) this field is ignored and real-time balance information will be fetched. If this field is not ignored, and no acceptable balance is available, an `INVALID_RESULT` error with the code `LAST_UPDATED_DATETIME_OUT_OF_RANGE` will be returned. Format: `date-time` ```node // Pull real-time balance information for each account associated // with the Item const request: AccountsGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.accountsBalanceGet(request); const accounts = response.data.accounts; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/accounts/balance/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "options": { "account_ids": [String] } }' ``` ```ruby # Pull real-time balance information for each account associated # with the Item request = Plaid::AccountsBalanceGetRequest.new({ access_token: access_token }) response = client.accounts_balance_get(request) accounts = response.accounts ``` ```java // Pull real-time balance information for each account associated // with the Item AccountsBalanceGetRequest request = new AccountsBalanceGetRequest() .accessToken(accessToken); Response response = client() .accountsBalanceGet(request) .execute(); List accounts = response.body().getAccounts(); ``` ```python # Pull real-time balance information for each account associated # with the Item request = AccountsBalanceGetRequest(access_token=access_token) response = client.accounts_balance_get(request) accounts = response['accounts'] ``` ```go balancesGetReq := plaid.NewAccountsBalanceGetRequest(accessToken) balancesGetResp, _, err = client.PlaidApi.AccountsBalanceGet(ctx).AccountsBalanceGetRequest( *balancesGetReq, ).Execute() ``` #### Response fields  \[object\] An array of financial institution accounts associated with the Item. If `/accounts/balance/get` was called, each account will include real-time balance information. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "accounts": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "holder_category": "personal", "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" }, { "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "balances": { "available": null, "current": 410, "iso_currency_code": "USD", "limit": 2000, "unofficial_currency_code": null }, "mask": "3333", "name": "Plaid Credit Card", "official_name": "Plaid Diamond 12.5% APR Interest Credit Card", "subtype": "credit card", "type": "credit" }, { "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE", "balances": { "available": null, "current": 65262, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "7777", "name": "Plaid Student Loan", "official_name": null, "subtype": "student", "type": "loan" } ], "item": { "available_products": [ "balance", "identity", "investments" ], "billed_products": [ "assets", "auth", "liabilities", "transactions" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_3", "institution_name": "Chase", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook", "auth_method": "INSTANT_AUTH" }, "request_id": "qk5Bxes3gDfv4F2" } ``` --- # API - Statements | Plaid Docs Statements  =========== #### API reference for Statements endpoints and webhooks  For how-to guidance, see the [Statements documentation](https://plaid.com/docs/statements/index.html.md) . | Endpoint | Description | | --- | --- | | [/statements/list](https://plaid.com/docs/api/products/statements/index.html.md#statementslist) | Get a list of statements available to download | | [/statements/download](https://plaid.com/docs/api/products/statements/index.html.md#statementsdownload) | Download a single bank statement | | [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) | Trigger on-demand statement extractions | | Webhook Name | Description | | --- | --- | | [STATEMENTS\_REFRESH\_COMPLETE](https://plaid.com/docs/api/products/statements/index.html.md#statements_refresh_complete) | Statements refresh completed | ### Endpoints  \=\*=\*=\*= #### /statements/list  #### Retrieve a list of all statements associated with an item.  The [/statements/list](https://plaid.com/docs/api/products/statements/index.html.md#statementslist) endpoint retrieves a list of all statements associated with an item. #### Request fields  required, string The access token associated with the Item data is being requested for. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```python request = StatementsListRequest(access_token=access_token) response = client.statements_list(request) accounts = response['accounts'] statements = accounts[0]['statements'] ``` ```bash curl -X POST https://sandbox.plaid.com/statements/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```java StatementsListRequest statementsListRequest = new StatementsListRequest().accessToken(accessToken); Response statementsListResponse = client.statementsList(statementsListRequest).execute(); List accounts = statementsListResponse.body().getAccounts(); List statements = accounts.get(0).getStatements(); ``` ```ruby statements_list_request = Plaid::StatementsListRequest.new statements_list_request.access_token = access_token response = client.statements_list(statements_list_request) accounts = response.accounts statements = accounts[0].statements ``` ```node const listRequest: StatementsListRequest = { access_token: access_token, }; const listResponse = await plaidClient.statementsList(listRequest); accounts = listResponse.accounts; statements = listResponse.accounts[0].statements; ``` ```go statementsListRequest := plaid.NewStatementsListRequest(accessToken) statementsListResponse, _, err := client.PlaidApi.StatementsList(ctx).StatementsListRequest(*statementsListRequest).Execute() accounts := statementsListResponse.GetAccounts() statements := accounts[0].GetStatements() ``` #### Response fields  \[object\] string Plaid's unique identifier for the account. string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user. string The name of the account, either assigned by the user or by the financial institution itself. string The official name of the account as given by the financial institution. string The subtype of the account. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . string The type of account. For a full list of valid types and subtypes, see the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) . \[object\] The list of statements' metadata associated with this account. string Plaid's unique identifier for the statement. nullable, string Date when the statement was posted by the FI, if known Format: `date` integer Month of the year. Possible values: 1 through 12 (January through December). integer The year of statement. Minimum: `2010` string The Plaid Institution ID associated with the Item. string The name of the institution associated with the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "institution_id": "ins_3", "institution_name": "Chase", "accounts": [ { "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "account_mask": "0000", "account_name": "Plaid Saving", "account_official_name": "Plaid Silver Standard 0.1% Interest Saving", "account_subtype": "savings", "account_type": "depository", "statements": [ { "statement_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "month": 5, "year": 2023, "date_posted": "2023-05-01" } ] } ], "request_id": "eYupqX1mZkEuQRx" } ``` \=\*=\*=\*= #### /statements/download  #### Retrieve a single statement.  The [/statements/download](https://plaid.com/docs/api/products/statements/index.html.md#statementsdownload) endpoint retrieves a single statement PDF in binary format. The response will contain a `Plaid-Content-Hash` header containing a SHA 256 checksum of the statement. This can be used to verify that the file being sent by Plaid is the same file that was downloaded to your system. #### Request fields  required, string The access token associated with the Item data is being requested for. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid's unique identifier for the statement. ```python request = StatementsDownloadRequest( access_token=access_token, statement_id=statement_id, ) pdf, status_code, headers = client.statements_download(request, _return_http_data_only=False) ``` ```bash curl -X POST https://sandbox.plaid.com/statements/download \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "statement_id": String }' ``` ```java StatementsDownloadRequest statementsDownloadRequest = new StatementsDownloadRequest().accessToken(accessToken).statementId(statementID); Response response = client.statementsDownload(statementsDownloadRequest).execute(); byte[] pdf = response.body().bytes(); ``` ```ruby statements_download_request = Plaid::StatementsDownloadRequest.new statements_download_request.access_token = access_token statements_download_request.statement_id = statement.statement_id pdf, status_code, headers = client.statements_download_with_http_info(statements_download_request) ``` ```node let downloadRequest: StatementsDownloadRequest = { access_token: accessToken, statement_id: statement.statement_id, }; let downloadResponse = await plaidClient.statementsDownload( downloadRequest, {responseType: 'arraybuffer'}, ); let pdf = downloadResponse.data.toString('base64'); ``` ```go downloadRequest := plaid.NewStatementsDownloadRequest(accessToken, statement.GetStatementId()) _, downloadResponse, err := client.PlaidApi.StatementsDownload(ctx).StatementsDownloadRequest(*downloadRequest).Execute() if err != nil { return err } pdf, err := ioutil.ReadAll(downloadResponse.Body) ``` ##### Response  This endpoint returns a single statement, exactly as provided by the financial institution, in the form of binary PDF data. \=\*=\*=\*= #### /statements/refresh  #### Refresh statements data.  [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) initiates an on-demand extraction to fetch the statements for the provided dates. #### Request fields  required, string The access token associated with the Item data is being requested for. string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The start date for statements, in "YYYY-MM-DD" format, e.g. "2023-08-30". To determine whether a statement falls within the specified date range, Plaid will use the statement posted date. The statement posted date is typically either the last day of the statement period, or the following day. Format: `date` required, string The end date for statements, in "YYYY-MM-DD" format, e.g. "2023-10-30". You can request up to two years of data. To determine whether a statement falls within the specified date range, Plaid will use the statement posted date. The statement posted date is typically either the last day of the statement period, or the following day. Format: `date` ```python request = StatementsRefreshRequest( access_token=access_token, start_date=date.today() - timedelta(days=90), end_date=date.today(), ) response = client.statements_refresh(request) ``` ```bash curl -X POST https://sandbox.plaid.com/statements/refresh \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "start_date": "2023-08-01", "end_date": "2023-11-01" }' ``` ```java StatementsRefreshRequest statementsRefreshRequest = new StatementsRefreshRequest().accessToken(accessToken).startDate(LocalDate.parse(startDate)).endDate(LocalDate.parse(endDate)); response = client.statementsRefresh(statementsRefreshRequest).execute(); ``` ```ruby statements_refresh_request = Plaid::StatementsRefreshRequest.new statements_refresh_request.access_token = access_token statements_refresh_request.start_date = Date.today.prev_year statements_refresh_request.end_date = Date.today.prev_month(10) response = client.statements_refresh(statements_refresh_request) ``` ```node const refreshRequest: StatementsRefreshRequest = { access_token: accessToken, start_date: '2023-11-01', end_date: '2024-02-01', }; const refreshResponse = await plaidClient.statementsRefresh(refreshRequest); ``` ```go startDate, endDate := "2023-11-01", "2024-01-01" refreshRequest := plaid.NewStatementsRefreshRequest(accessToken, startDate, endDate) refreshResponse, _, err := client.PlaidApi.StatementsRefresh(ctx).StatementsRefreshRequest(*refreshRequest).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "eYupqX1mZkEuQRx" } ``` ### Webhooks  Statement webhooks are sent to indicate that statements refresh has finished processing. All webhooks related to statements have a `webhook_type` of `STATEMENTS`. \=\*=\*=\*= #### STATEMENTS\_REFRESH\_COMPLETE  Fired when refreshed statements extraction is completed or failed to be completed. Triggered by calling [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) . #### Properties  string `STATEMENTS` string `STATEMENTS_REFRESH_COMPLETE` string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. string The result of the statement refresh extraction `SUCCESS`: The statements were successfully extracted and can be listed via `/statements/list/` and downloaded via `/statements/download/`. `FAILURE`: The statements failed to be extracted. Possible values: `SUCCESS`, `FAILURE` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "STATEMENTS", "webhook_code": "STATEMENTS_REFRESH_COMPLETE", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "result": "SUCCESS", "environment": "production" } ``` --- # API - Transactions | Plaid Docs Transactions  ============= #### API reference for Transactions endpoints and webhooks  Retrieve and refresh up to 24 months of historical transaction data, including geolocation, merchant, and category information. For how-to guidance, see the [Transactions documentation](https://plaid.com/docs/transactions/index.html.md) . | Endpoints | | | --- | --- | | [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) | Get transaction data or incremental transaction updates | | [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) | Fetch transaction data | | [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) | Fetch recurring transaction data | | [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) | Refresh transaction data | | [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) | Fetch all transaction categories | | See also | | | --- | --- | | [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) | Get transaction data or incremental transaction updates | | [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) | Fetch transaction data | | [/processor/transactions/recurring/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrecurringget) | Fetch recurring transaction data | | [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) | Refresh transaction data | | [/sandbox/transactions/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransactionscreate) | Create custom transactions for testing | | Webhooks | | | --- | --- | | [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) | New updates available | | [RECURRING\_TRANSACTIONS\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#recurring_transactions_update) | New recurring updates available | | [INITIAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#initial_update) | Initial transactions ready | | [HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#historical_update) | Historical transactions ready | | [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#default_update) | New transactions available | | [TRANSACTIONS\_REMOVED](https://plaid.com/docs/api/products/transactions/index.html.md#transactions_removed) | Deleted transactions detected | ### Endpoints  \=\*=\*=\*= #### /transactions/sync  If you are migrating to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) from an existing [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) integration, also refer to the [Transactions Sync migration guide](https://plaid.com/docs/transactions/sync-migration/index.html.md) . #### Get incremental transaction updates on an Item  The [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint retrieves transactions associated with an Item and can fetch updates using a cursor to track which updates have already been seen. For important instructions on integrating with [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , see the [Transactions integration overview](https://plaid.com/docs/transactions/index.html.md#integration-overview) . If you are migrating from an existing integration using [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , see the [Transactions Sync migration guide](https://plaid.com/docs/transactions/sync-migration/index.html.md) . This endpoint supports `credit`, `depository`, and some `loan`\-type accounts (only those with account subtype `student`). For `investments` accounts, use [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) instead. When retrieving paginated updates, track both the `next_cursor` from the latest response and the original cursor from the first call in which `has_more` was `true`; if a call to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) fails when retrieving a paginated update (e.g due to the [TRANSACTIONS\_SYNC\_MUTATION\_DURING\_PAGINATION](https://plaid.com/docs/errors/transactions/index.html.md#transactions_sync_mutation_during_pagination) error), the entire pagination request loop must be restarted beginning with the cursor for the first page of the update, rather than retrying only the single request that failed. If transactions data is not yet available for the Item, which can happen if the Item was not initialized with transactions during the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call or if [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) was called within a few seconds of Item creation, [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) will return empty transactions arrays. Plaid typically checks for new transactions data between one and four times per day, depending on the institution. To find out when transactions were last updated for an Item, use the [Item Debugger](https://plaid.com/docs/account/activity/index.html.md#troubleshooting-with-item-debugger) or call [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) ; the `item.status.transactions.last_successful_update` field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, use the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint. To be alerted when new transactions are available, listen for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) webhook. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string The access token associated with the Item data is being requested for. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The cursor value represents the last update requested. Providing it will cause the response to only return changes after this update. If omitted, the entire history of updates will be returned, starting with the first-added transactions on the Item. The cursor also accepts the special value of `"now"`, which can be used to fast-forward the cursor as part of migrating an existing Item from `/transactions/get` to `/transactions/sync`. For more information, see the [Transactions sync migration guide](https://plaid.com/docs/transactions/sync-migration/index.html.md) . Note that using the `"now"` value is not supported for any use case other than migrating existing Items from `/transactions/get`. The upper-bound length of this cursor is 256 characters of base64. integer The number of transaction updates to fetch. Default: `100` Minimum: `1` Maximum: `500` Exclusive min: `false` object An optional object to be used with the request. If specified, `options` must not be `null`. boolean Include the raw unparsed transaction description from the financial institution. Default: `false` string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` integer This field only applies to calls for Items where the Transactions product has not already been initialized (i.e., by specifying `transactions` in the `products`, `required_if_supported_products`, or `optional_products` array when calling `/link/token/create` or by making a previous call to `/transactions/sync` or `/transactions/get`). In those cases, the field controls the maximum number of days of transaction history that Plaid will request from the financial institution. The more transaction history is requested, the longer the historical update poll will take. If no value is specified, 90 days of history will be requested by default. In Production, if a value less than 30 is provided, a minimum of 30 days of transaction history will be requested. If you are initializing your Items with transactions during the `/link/token/create` call (e.g. by including `transactions` in the `/link/token/create` `products` array), you must use the [transactions.days\_requested](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transactions-days-requested) field in the `/link/token/create` request instead of in the `/transactions/sync` request. If the Item has already been initialized with the Transactions product, this field will have no effect. The maximum amount of transaction history to request on an Item cannot be updated if Transactions has already been added to the Item. To request older transaction history on an Item where Transactions has already been added, you must delete the Item via `/item/remove` and send the user through Link to create a new Item. Customers using [Recurring Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) should request at least 180 days of history for optimal results. Minimum: `1` Maximum: `730` Default: `90` string If provided, the returned updates and cursor will only reflect the specified account's transactions. Omitting `account_id` returns updates for all accounts under the Item. Note that specifying an `account_id` effectively creates a separate incremental update stream—and therefore a separate cursor—for that account. If multiple accounts are queried this way, you will maintain multiple cursors, one per `account_id`. If you decide to begin filtering by `account_id` after using no `account_id`, start fresh with a null cursor and maintain separate `(account_id, cursor)` pairs going forward. Do not reuse any previously saved cursors, as this can cause pagination errors or incomplete data. Note: An error will be returned if a provided `account_id` is not associated with the Item. ```node // Provide a cursor from your database if you've previously // received one for the Item. Leave null if this is your // first sync call for this Item. The first request will // return a cursor. let cursor = database.getLatestCursorOrNull(itemId); // New transaction updates since "cursor" let added: Array = []; let modified: Array = []; // Removed transaction ids let removed: Array = []; let hasMore = true; // Iterate through each page of new transaction updates for item while (hasMore) { const request: TransactionsSyncRequest = { access_token: accessToken, cursor: cursor, }; const response = await client.transactionsSync(request); const data = response.data; // Add this page of results added = added.concat(data.added); modified = modified.concat(data.modified); removed = removed.concat(data.removed); hasMore = data.has_more; // Update cursor to the next cursor cursor = data.next_cursor; } // Persist cursor and updated data database.applyUpdates(itemId, added, modified, removed, cursor); ``` ```bash curl -X POST https://sandbox.plaid.com/transactions/sync \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "cursor": String, "count": 250 }' ``` ```ruby # Provide a cursor from your database if you've previously # received one for the Item. Leave null if this is your # first sync call for this item. The first request will # return a cursor. cursor = database.get_latest_cursor_or_none(item_id) # New transaction updates since "cursor" added = [] modified = [] removed = [] # Removed transaction ids has_more = true # Iterate through each page of new transaction updates for item while has_more request = Plaid::TransactionsSyncRequest.new( { access_token: access_token, cursor: cursor, } ) response = client.transactions_sync(request) # Add this page of results added += response.added modified += response.modified removed += response.removed has_more = response.has_more # Update cursor to the next cursor cursor = response.next_cursor end # Persist cursor and updated data database.apply_updates(item_id, added, modified, removed, cursor) ``` ```java // Provide a cursor from your database if you've previously // received one for the item leave null if this is your // first sync call for this item. The first request will // return a cursor. String cursor = database.getLatestCursorOrNull(itemId); // New transaction updates since "cursor" List added = new ArrayList(); List modified = new ArrayList(); List removed = new ArrayList(); boolean hasMore = true; TransactionsSyncRequestOptions options = new TransactionsSyncRequestOptions() .includePersonalFinanceCategory(true); // Iterate through each page of new transaction updates for item while (hasMore) { TransactionsSyncRequest request = new TransactionsSyncRequest() .accessToken(accessToken) .cursor(cursor) .options(options); response = plaidClient.transactionsSync(request).execute(); // Add this page of results added.addAll(response.getAdded()); modified.addAll(response.getModified()); removed.addAll(response.getRemoved()); hasMore = response.getHasMore(); // Update cursor to the next cursor cursor = response.getNextCursor(); } // Persist cursor and updated data database.applyUpdates(itemId, added, modified, removed, cursor); ``` ```python # Provide a cursor from your database if you've previously # received one for the Item. Leave null if this is your # first sync call for this Item. The first request will # return a cursor. cursor = database.get_latest_cursor_or_none(item_id) # New transaction updates since "cursor" added = [] modified = [] removed = [] # Removed transaction ids has_more = True # Iterate through each page of new transaction updates for item while has_more: request = TransactionsSyncRequest( access_token=access_token, cursor=cursor, ) response = plaid_client.transactions_sync(request) # Add this page of results added.extend(response['added']) modified.extend(response['modified']) removed.extend(response['removed']) has_more = response['has_more'] # Update cursor to the next cursor cursor = response['next_cursor'] # Persist cursor and updated data database.apply_updates(item_id, added, modified, removed, cursor) ``` ```go // Provide a cursor from your database if you've previously // received one for the Item. Leave null if this is your // first sync call for this Item. The first request will // return a cursor. cursor := database.getLatestCursorOrNil(itemId) // New transaction updates since "cursor" var added []Transaction var modified []Transaction var removed []RemovedTransaction // Removed transaction ids hasMore := true options := plaid.TransactionsSyncRequestOptions{ IncludePersonalFinanceCategory: true, } // Iterate through each page of new transaction updates for item for hasMore { request := plaid.NewTransactionsSyncRequest(accessToken) request.SetOptions(options) if cursor != nil { request.SetCursor(*cursor) } resp, _, err := client.PlaidApi.TransactionsSync( ctx, ).TransactionsSyncRequest(*request).Execute() // Add this page of results added = append(added, resp.GetAdded()...) modified = append(modified, resp.GetModified()...) removed = append(removed, resp.GetRemoved()...) hasMore = resp.GetHasMore() // Update cursor to the next cursor cursor = &resp.GetNextCursor() } // Persist cursor and updated data database.applyUpdates(itemId, added, modified, removed, cursor) ``` #### Response fields  string A description of the update status for transaction pulls of an Item. This field contains the same information provided by transactions webhooks, and may be helpful for webhook troubleshooting or when recovering from missed webhooks. `TRANSACTIONS_UPDATE_STATUS_UNKNOWN`: Unable to fetch transactions update status for Item. `NOT_READY`: The Item is pending transaction pull. `INITIAL_UPDATE_COMPLETE`: Initial pull for the Item is complete, historical pull is pending. `HISTORICAL_UPDATE_COMPLETE`: Both initial and historical pull for Item are complete. Possible values: `TRANSACTIONS_UPDATE_STATUS_UNKNOWN`, `NOT_READY`, `INITIAL_UPDATE_COMPLETE`, `HISTORICAL_UPDATE_COMPLETE` \[object\] An array of accounts at a financial institution associated with the transactions in this response. Only accounts that have associated transactions will be shown. For example, `investment`\-type accounts will be omitted. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] Transactions that have been added to the Item since `cursor` ordered by ascending last modified time. string The ID of the account in which this transaction occurred. number The settled value of the transaction, denominated in the transactions's currency, as stated in `iso_currency_code` or `unofficial_currency_code`. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: `double` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The check number of the transaction. This field is only populated for check transactions. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). To receive information about the date that a posted transaction was initiated, see the `authorized_date` field. Format: `date` object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. deprecated, string The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use `merchant_name` instead for the merchant name. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, this field will always appear. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The merchant name, as enriched by Plaid from the `name` field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be `null`. nullable, string The string returned by the financial institution to describe the transaction. For transactions returned by `/transactions/sync` or `/transactions/get`, this field will only be included if the client has set `options.include_original_description` to `true`. object Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be `null`. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, the `payment_meta` key will always appear, but no data elements are guaranteed. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The transaction reference number supplied by the financial institution. nullable, string The ACH PPD ID for the payer. nullable, string For transfers, the party that is receiving the transaction. nullable, string The party initiating a wire transfer. Will be `null` if the transaction is not a wire transfer. nullable, string For transfers, the party that is paying the transaction. nullable, string The type of transfer, e.g. 'ACH' nullable, string The name of the payment processor nullable, string The payer-supplied description of the transfer. boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions. nullable, string The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions. nullable, string This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. deprecated, string Please use the `payment_channel` field, `transaction_type` will be deprecated in the future. `digital:` transactions that took place online. `place:` transactions that were made at a physical location. `special:` transactions that relate to banks, e.g. fees or deposits. `unresolved:` transactions that do not fit into the other three types. Possible values: `digital`, `place`, `special`, `unresolved` nullable, string The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file. nullable, string The website associated with this transaction, if available. nullable, string The date that the transaction was authorized. For posted transactions, the `date` field will indicate the posted date, but `authorized_date` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_date`, when available, is generally preferable to use over the `date` field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). Format: `date` nullable, string Date and time when a transaction was authorized in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For posted transactions, the `datetime` field will indicate the posted date, but `authorized_datetime` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_datetime`, when available, is generally preferable to use over the `datetime` field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` nullable, string Date and time when a transaction was posted in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For the date that the transaction was initiated, rather than posted, see the `authorized_datetime` field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` string The channel used to make a payment. `online:` transactions that took place online. `in store:` transactions that were made at a physical location. `other:` transactions that relate to banks, e.g. fees or deposits. This field replaces the `transaction_type` field. Possible values: `online`, `in store`, `other` nullable, object Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the [taxonomy CSV file](https://plaid.com/documents/pfc-taxonomy-all.csv) for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the [migration guide](https://plaid.com/docs/transactions/pfc-migration/index.html.md) . string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string A description of how confident we are that the provided categories accurately describe the transaction intent. `VERY_HIGH`: We are more than 98% confident that this category reflects the intent of the transaction. `HIGH`: We are more than 90% confident that this category reflects the intent of the transaction. `MEDIUM`: We are moderately confident that this category reflects the intent of the transaction. `LOW`: This category may reflect the intent, but there may be other categories that are more accurate. `UNKNOWN`: We don’t know the confidence level for this category. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` nullable, string An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to `null`. `adjustment:` Bank adjustment `atm:` Cash deposit or withdrawal via an automated teller machine `bank charge:` Charge or fee levied by the institution `bill payment`: Payment of a bill `cash:` Cash deposit or withdrawal `cashback:` Cash withdrawal while making a debit card purchase `cheque:` Document ordering the payment of money to another person or organization `direct debit:` Automatic withdrawal of funds initiated by a third party at a regular interval `interest:` Interest earned or incurred `purchase:` Purchase made with a debit or credit card `standing order:` Payment instructed by the account holder to a third party at a regular interval `transfer:` Transfer of money between accounts Possible values: `adjustment`, `atm`, `bank charge`, `bill payment`, `cash`, `cashback`, `cheque`, `direct debit`, `interest`, `purchase`, `standing order`, `transfer`, `null` string The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file. \[object\] The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description. string The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description. nullable, string A unique, stable, Plaid-generated ID that maps to the counterparty. string The counterparty type. `merchant`: a provider of goods or services for purchase `financial_institution`: a financial entity (bank, credit union, BNPL, fintech) `payment_app`: a transfer or P2P app (e.g. Zelle) `marketplace`: a marketplace (e.g DoorDash, Google Play Store) `payment_terminal`: a point-of-sale payment terminal (e.g Square, Toast) `income_source`: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: `merchant`, `financial_institution`, `payment_app`, `marketplace`, `payment_terminal`, `income_source` nullable, string The website associated with the counterparty. nullable, string The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file. nullable, string A description of how confident we are that the provided counterparty is involved in the transaction. `VERY_HIGH`: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. `HIGH`: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. `MEDIUM`: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. `LOW`: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. `UNKNOWN`: We don’t know the confidence level for this counterparty. nullable, object Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe. nullable, object Identifying information for a UK bank account via BACS. nullable, string The BACS account number for the account. nullable, string The BACS sort code for the account. nullable, object Account numbers using the International Bank Account Number and BIC/SWIFT code format. nullable, string International Bank Account Number (IBAN). Min length: `15` Max length: `34` nullable, string Bank identifier code (BIC) for this counterparty. Min length: `8` Max length: `11` nullable, string A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store. \[object\] Transactions that have been modified on the Item since `cursor` ordered by ascending last modified time. string The ID of the account in which this transaction occurred. number The settled value of the transaction, denominated in the transactions's currency, as stated in `iso_currency_code` or `unofficial_currency_code`. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: `double` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The check number of the transaction. This field is only populated for check transactions. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). To receive information about the date that a posted transaction was initiated, see the `authorized_date` field. Format: `date` object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. deprecated, string The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use `merchant_name` instead for the merchant name. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, this field will always appear. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The merchant name, as enriched by Plaid from the `name` field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be `null`. nullable, string The string returned by the financial institution to describe the transaction. For transactions returned by `/transactions/sync` or `/transactions/get`, this field will only be included if the client has set `options.include_original_description` to `true`. object Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be `null`. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, the `payment_meta` key will always appear, but no data elements are guaranteed. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The transaction reference number supplied by the financial institution. nullable, string The ACH PPD ID for the payer. nullable, string For transfers, the party that is receiving the transaction. nullable, string The party initiating a wire transfer. Will be `null` if the transaction is not a wire transfer. nullable, string For transfers, the party that is paying the transaction. nullable, string The type of transfer, e.g. 'ACH' nullable, string The name of the payment processor nullable, string The payer-supplied description of the transfer. boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions. nullable, string The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions. nullable, string This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. deprecated, string Please use the `payment_channel` field, `transaction_type` will be deprecated in the future. `digital:` transactions that took place online. `place:` transactions that were made at a physical location. `special:` transactions that relate to banks, e.g. fees or deposits. `unresolved:` transactions that do not fit into the other three types. Possible values: `digital`, `place`, `special`, `unresolved` nullable, string The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file. nullable, string The website associated with this transaction, if available. nullable, string The date that the transaction was authorized. For posted transactions, the `date` field will indicate the posted date, but `authorized_date` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_date`, when available, is generally preferable to use over the `date` field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). Format: `date` nullable, string Date and time when a transaction was authorized in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For posted transactions, the `datetime` field will indicate the posted date, but `authorized_datetime` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_datetime`, when available, is generally preferable to use over the `datetime` field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` nullable, string Date and time when a transaction was posted in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For the date that the transaction was initiated, rather than posted, see the `authorized_datetime` field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` string The channel used to make a payment. `online:` transactions that took place online. `in store:` transactions that were made at a physical location. `other:` transactions that relate to banks, e.g. fees or deposits. This field replaces the `transaction_type` field. Possible values: `online`, `in store`, `other` nullable, object Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the [taxonomy CSV file](https://plaid.com/documents/pfc-taxonomy-all.csv) for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the [migration guide](https://plaid.com/docs/transactions/pfc-migration/index.html.md) . string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string A description of how confident we are that the provided categories accurately describe the transaction intent. `VERY_HIGH`: We are more than 98% confident that this category reflects the intent of the transaction. `HIGH`: We are more than 90% confident that this category reflects the intent of the transaction. `MEDIUM`: We are moderately confident that this category reflects the intent of the transaction. `LOW`: This category may reflect the intent, but there may be other categories that are more accurate. `UNKNOWN`: We don’t know the confidence level for this category. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` nullable, string An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to `null`. `adjustment:` Bank adjustment `atm:` Cash deposit or withdrawal via an automated teller machine `bank charge:` Charge or fee levied by the institution `bill payment`: Payment of a bill `cash:` Cash deposit or withdrawal `cashback:` Cash withdrawal while making a debit card purchase `cheque:` Document ordering the payment of money to another person or organization `direct debit:` Automatic withdrawal of funds initiated by a third party at a regular interval `interest:` Interest earned or incurred `purchase:` Purchase made with a debit or credit card `standing order:` Payment instructed by the account holder to a third party at a regular interval `transfer:` Transfer of money between accounts Possible values: `adjustment`, `atm`, `bank charge`, `bill payment`, `cash`, `cashback`, `cheque`, `direct debit`, `interest`, `purchase`, `standing order`, `transfer`, `null` string The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file. \[object\] The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description. string The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description. nullable, string A unique, stable, Plaid-generated ID that maps to the counterparty. string The counterparty type. `merchant`: a provider of goods or services for purchase `financial_institution`: a financial entity (bank, credit union, BNPL, fintech) `payment_app`: a transfer or P2P app (e.g. Zelle) `marketplace`: a marketplace (e.g DoorDash, Google Play Store) `payment_terminal`: a point-of-sale payment terminal (e.g Square, Toast) `income_source`: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: `merchant`, `financial_institution`, `payment_app`, `marketplace`, `payment_terminal`, `income_source` nullable, string The website associated with the counterparty. nullable, string The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file. nullable, string A description of how confident we are that the provided counterparty is involved in the transaction. `VERY_HIGH`: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. `HIGH`: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. `MEDIUM`: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. `LOW`: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. `UNKNOWN`: We don’t know the confidence level for this counterparty. nullable, object Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe. nullable, object Identifying information for a UK bank account via BACS. nullable, string The BACS account number for the account. nullable, string The BACS sort code for the account. nullable, object Account numbers using the International Bank Account Number and BIC/SWIFT code format. nullable, string International Bank Account Number (IBAN). Min length: `15` Max length: `34` nullable, string Bank identifier code (BIC) for this counterparty. Min length: `8` Max length: `11` nullable, string A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store. \[object\] Transactions that have been removed from the Item since `cursor` ordered by ascending last modified time. string The ID of the removed transaction. string The ID of the account of the removed transaction. string Cursor used for fetching any future updates after the latest update provided in this response. The cursor obtained after all pages have been pulled (indicated by `has_more` being `false`) will be valid for at least 1 year. This cursor should be persisted for later calls. If transactions are not yet available, this will be an empty string. If `account_id` is included in the request, the returned cursor will reflect updates for that specific account. boolean Represents if more than requested count of transaction updates exist. If true, the additional updates can be fetched by making an additional request with `cursor` set to `next_cursor`. If `has_more` is true, it’s important to pull all available pages, to make it less likely for underlying data changes to conflict with pagination. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "accounts": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": 110.94, "current": 110.94, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" } ], "added": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "account_owner": null, "amount": 72.1, "iso_currency_code": "USD", "unofficial_currency_code": null, "check_number": null, "counterparties": [ { "name": "Walmart", "type": "merchant", "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "website": "walmart.com", "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM", "confidence_level": "VERY_HIGH" } ], "date": "2023-09-24", "datetime": "2023-09-24T11:01:01Z", "authorized_date": "2023-09-22", "authorized_datetime": "2023-09-22T10:34:50Z", "location": { "address": "13425 Community Rd", "city": "Poway", "region": "CA", "postal_code": "92064", "country": "US", "lat": 32.959068, "lon": -117.037666, "store_number": "1700" }, "name": "PURCHASE WM SUPERCENTER #1700", "merchant_name": "Walmart", "merchant_entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM", "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "website": "walmart.com", "payment_meta": { "by_order_of": null, "payee": null, "payer": null, "payment_method": null, "payment_processor": null, "ppd_id": null, "reason": null, "reference_number": null }, "payment_channel": "in store", "pending": false, "pending_transaction_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc", "personal_finance_category": { "primary": "GENERAL_MERCHANDISE", "detailed": "GENERAL_MERCHANDISE_SUPERSTORES", "confidence_level": "VERY_HIGH" }, "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png", "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje", "transaction_code": null, "transaction_type": "place" } ], "modified": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "account_owner": null, "amount": 28.34, "iso_currency_code": "USD", "unofficial_currency_code": null, "check_number": null, "counterparties": [ { "name": "DoorDash", "type": "marketplace", "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png", "website": "doordash.com", "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm", "confidence_level": "HIGH" }, { "name": "Burger King", "type": "merchant", "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png", "website": "burgerking.com", "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1", "confidence_level": "VERY_HIGH" } ], "date": "2023-09-28", "datetime": "2023-09-28T15:10:09Z", "authorized_date": "2023-09-27", "authorized_datetime": "2023-09-27T08:01:58Z", "location": { "address": null, "city": null, "region": null, "postal_code": null, "country": null, "lat": null, "lon": null, "store_number": null }, "name": "Dd Doordash Burgerkin", "merchant_name": "Burger King", "merchant_entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1", "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png", "website": "burgerking.com", "payment_meta": { "by_order_of": null, "payee": null, "payer": null, "payment_method": null, "payment_processor": null, "ppd_id": null, "reason": null, "reference_number": null }, "payment_channel": "online", "pending": true, "pending_transaction_id": null, "personal_finance_category": { "primary": "FOOD_AND_DRINK", "detailed": "FOOD_AND_DRINK_FAST_FOOD", "confidence_level": "VERY_HIGH" }, "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png", "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0", "transaction_code": null, "transaction_type": "digital" } ], "removed": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "transaction_id": "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l" } ], "next_cursor": "tVUUL15lYQN5rBnfDIc1I8xudpGdIlw9nsgeXWvhOfkECvUeR663i3Dt1uf/94S8ASkitgLcIiOSqNwzzp+bh89kirazha5vuZHBb2ZA5NtCDkkV", "has_more": false, "request_id": "Wvhy9PZHQLV8njG", "transactions_update_status": "HISTORICAL_UPDATE_COMPLETE" } ``` \=\*=\*=\*= #### /transactions/get  #### Get transaction data  Note: All new implementations are encouraged to use [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) rather than [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) . [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) provides the same functionality as [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) and improves developer ease-of-use for handling transactions updates. The [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) endpoint allows developers to receive user-authorized transaction data for credit, depository, and some loan-type accounts (only those with account subtype `student`; coverage may be limited). For transaction history from investments accounts, use the [Investments endpoint](https://plaid.com/docs/api/products/investments/index.html.md) instead. Transaction data is standardized across financial institutions, and in many cases transactions are linked to a clean name, entity type, location, and category. Similarly, account data is standardized and returned with a clean name, number, balance, and other meta information where available. Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift. Transactions are not immutable and can also be removed altogether by the institution; a removed transaction will no longer appear in [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) . For more details, see [Pending and posted transactions](https://plaid.com/docs/transactions/transactions-data/index.html.md#pending-and-posted-transactions) . Due to the potentially large number of transactions associated with an Item, results are paginated. Manipulate the `count` and `offset` parameters in conjunction with the `total_transactions` response body field to fetch all available transactions. Data returned by [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) will be the data available for the Item as of the most recent successful check for new transactions. Plaid typically checks for new data multiple times a day, but these checks may occur less frequently, such as once a day, depending on the institution. To find out when the Item was last updated, use the [Item Debugger](https://plaid.com/docs/account/activity/index.html.md#troubleshooting-with-item-debugger) or call [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) ; the `item.status.transactions.last_successful_update` field will show the timestamp of the most recent successful update. To force Plaid to check for new transactions, you can use the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint. Note that data may not be immediately available to [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) . Plaid will begin to prepare transactions data upon Item link, if Link was initialized with `transactions`, or upon the first call to [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , if it wasn't. To be alerted when transaction data is ready to be fetched, listen for the [INITIAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#initial_update) and [HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#historical_update) webhooks. If no transaction history is ready when [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) is called, it will return a `PRODUCT_NOT_READY` error. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. object An optional object to be used with the request. If specified, `options` must not be `null`. \[string\] A list of `account_ids` to retrieve for the Item Note: An error will be returned if a provided `account_id` is not associated with the Item. integer The number of transactions to fetch. Default: `100` Minimum: `1` Maximum: `500` Exclusive min: `false` integer The number of transactions to skip. The default value is 0. Default: `0` Minimum: `0` boolean Include the raw unparsed transaction description from the financial institution. Default: `false` string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` integer This field only applies to calls for Items where the Transactions product has not already been initialized (i.e. by specifying `transactions` in the `products`, `optional_products`, or `required_if_consented_products` array when calling `/link/token/create` or by making a previous call to `/transactions/sync` or `/transactions/get`). In those cases, the field controls the maximum number of days of transaction history that Plaid will request from the financial institution. The more transaction history is requested, the longer the historical update poll will take. If no value is specified, 90 days of history will be requested by default. In Production, if a value under 30 is provided, a minimum of 30 days of history will be requested. If you are initializing your Items with transactions during the `/link/token/create` call (e.g. by including `transactions` in the `/link/token/create` `products` array), you must use the [transactions.days\_requested](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transactions-days-requested) field in the `/link/token/create` request instead of in the `/transactions/get` request. If the Item has already been initialized with the Transactions product, this field will have no effect. The maximum amount of transaction history to request on an Item cannot be updated if Transactions has already been added to the Item. To request older transaction history on an Item where Transactions has already been added, you must delete the Item via `/item/remove` and send the user through Link to create a new Item. Customers using [Recurring Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) should request at least 180 days of history for optimal results. Minimum: `1` Maximum: `730` Default: `90` required, string The access token associated with the Item data is being requested for. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: `date` required, string The latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD. Format: `date` ```node const request: TransactionsGetRequest = { access_token: accessToken, start_date: '2018-01-01', end_date: '2020-02-01' }; try { const response = await client.transactionsGet(request); let transactions = response.data.transactions; const total_transactions = response.data.total_transactions; // Manipulate the offset parameter to paginate // transactions and retrieve all available data while (transactions.length < total_transactions) { const paginatedRequest: TransactionsGetRequest = { access_token: accessToken, start_date: '2018-01-01', end_date: '2020-02-01', options: { offset: transactions.length }, }; const paginatedResponse = await client.transactionsGet(paginatedRequest); transactions = transactions.concat( paginatedResponse.data.transactions, ); } } catch (err) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transactions/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "start_date": "2018-01-01", "end_date": "2018-02-01", "options": { "count": 250, "offset": 100 } }' ``` ```ruby start_date = (Date.today - 30) end_date = Date.today # Pull transactions for a date range request = Plaid::TransactionsGetRequest.new( { access_token: access_token, start_date: start_date, end_date: end_date } ) response = client.transactions_get(request) transactions = response.transactions # Manipulate the offset parameter to paginate # transactions and retrieve all available data while transactions.length < response.total_transactions request = Plaid::TransactionsGetRequest.new( { access_token: access_token, start_date: start_date, end_date: end_date, options: { offset: transactions.length } } ) response = client.transactions_get(request) transactions += response.transactions end ``` ```java LocalDate startDate = LocalDate.now().minusDays(30); LocalDate endDate = LocalDate.now(); TransactionsGetRequestOptions options = new TransactionsGetRequestOptions() .includePersonalFinanceCategory(true) // Pull transactions for a date range TransactionsGetRequest request = new TransactionsGetRequest() .accessToken(accessToken) .startDate(startDate) .endDate(endDate) .options(options); Response response = plaidClient.transactionsGet(request).execute(); List transactions = new ArrayList (); transactions.addAll(response.body().getTransactions()); // Manipulate the offset parameter to paginate // transactions and retrieve all available data while (transactions.size() < response.body().getTotalTransactions()) { options = new TransactionsGetRequestOptions() .offset(transactions.size()) .includePersonalFinanceCategory(true); TransactionsGetRequest request = new TransactionsGetRequest() .accessToken(accessToken) .startDate(startDate) .endDate(endDate) .options(options); Response response = plaidClient.transactionsGet(request).execute(); transactions.addAll(response.body().getTransactions()); } ``` ```python request = TransactionsGetRequest( access_token=access_token, start_date=datetime.date(2020, 1, 1), end_date=datetime.date(2021, 2, 1) ) response = client.transactions_get(request) transactions = response['transactions'] # Manipulate the count and offset parameters to paginate # transactions and retrieve all available data while len(transactions) < response['total_transactions']: request = TransactionsGetRequest( access_token=access_token, start_date=datetime.date(2018, 1, 1), end_date=datetime.date(2018, 2, 1), options=TransactionsGetRequestOptions( offset=len(transactions) ) ) response = client.transactions_get(request) transactions.extend(response['transactions']) ``` ```go const iso8601TimeFormat = "2006-01-02" startDate := time.Now().Add(-365 * 24 * time.Hour).Format(iso8601TimeFormat) endDate := time.Now().Format(iso8601TimeFormat) request := plaid.NewTransactionsGetRequest( accessToken, startDate, endDate, ) options := plaid.TransactionsGetRequestOptions{ Count: plaid.PtrInt32(100), Offset: plaid.PtrInt32(0), IncludePersonalFinanceCategory: true, } request.SetOptions(options) transactionsResp, _, err := client.PlaidApi.TransactionsGet(ctx).TransactionsGetRequest(*request).Execute() ``` #### Response fields  \[object\] An array containing the `accounts` associated with the Item for which transactions are being returned. Each transaction can be mapped to its corresponding account via the `account_id` field. string Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new `account_id` will be assigned to the account. The `account_id` can also change if the `access_token` is deleted and the same credentials that were used to generate that `access_token` are used to generate a new `access_token` on a later date. In that case, the new `account_id` will be different from the old `account_id`. If an account with a specific `account_id` disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. When using a CRA endpoint (an endpoint associated with Plaid Check Consumer Report, i.e. any endpoint beginning with `/cra/`), the `account_id` returned will not match the `account_id` returned by a non-CRA endpoint. Like all Plaid identifiers, the `account_id` is case sensitive. object A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by `/accounts/balance/get` or `/signal/evaluate` (using a Balance-only ruleset). nullable, number The amount of funds available to be withdrawn from the account, as determined by the financial institution. For `credit`\-type accounts, the `available` balance typically equals the `limit` less the `current` balance, less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance typically equals the `current` balance less any pending outflows plus any pending inflows. For `depository`\-type accounts, the `available` balance does not include the overdraft limit. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the `available` balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the `available` balance. In the event that `available` balance is unavailable, Plaid will return an `available` balance value of `null`. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by `/accounts/balance/get`, or by `/signal/evaluate` with a Balance-only ruleset. If `current` is `null` this field is guaranteed not to be `null`. Format: `double` nullable, number The total amount of funds in or owed by the account. For `credit`\-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For `loan`\-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (`ins_116944`). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. Similar to `credit`\-type accounts, a positive balance is typically expected, while a negative amount indicates the lender owing the account holder. For `investment`\-type accounts (or `brokerage`\-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by `/accounts/balance/get` or by `/signal/evaluate` with a Balance-only ruleset; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the `available` balance as provided by `/accounts/balance/get` or `/signal/evaluate` called with a Balance-only `ruleset_key`. When returned by `/accounts/balance/get`, this field may be `null`. When this happens, `available` is guaranteed not to be `null`. Format: `double` nullable, number For `credit`\-type accounts, this represents the credit limit. For `depository`\-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for `credit`\-type accounts. Format: `double` nullable, string The ISO-4217 currency code of the balance. Always null if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the balance. Always null if `iso_currency_code` is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. nullable, string Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time the balance was updated. This field is returned only when the institution is `ins_128026` (Capital One). Format: `date-time` nullable, string The last 2-4 alphanumeric characters of either the account’s displayed mask or the account’s official account number. Note that the mask may be non-unique between an Item’s accounts. string The name of the account, either assigned by the user or by the financial institution itself nullable, string The official name of the account as given by the financial institution string `investment:` Investment account. In API versions 2018-05-22 and earlier, this type is called `brokerage` instead. `credit:` Credit card `depository:` Depository account `loan:` Loan account `other:` Non-specified account type See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `investment`, `credit`, `depository`, `loan`, `brokerage`, `other` nullable, string See the [Account type schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full listing of account types and corresponding subtypes. Possible values: `401a`, `401k`, `403B`, `457b`, `529`, `auto`, `brokerage`, `business`, `cash isa`, `cash management`, `cd`, `checking`, `commercial`, `construction`, `consumer`, `credit card`, `crypto exchange`, `ebt`, `education savings account`, `fhsa`, `fixed annuity`, `gic`, `health reimbursement arrangement`, `home equity`, `hsa`, `isa`, `ira`, `keogh`, `lif`, `life insurance`, `limited purpose checking`, `line of credit`, `lira`, `loan`, `lrif`, `lrsp`, `money market`, `mortgage`, `mutual fund`, `non-custodial wallet`, `non-taxable brokerage account`, `other`, `other insurance`, `other annuity`, `overdraft`, `paypal`, `payroll`, `pension`, `prepaid`, `prif`, `profit sharing plan`, `qshr`, `rdsp`, `resp`, `retirement`, `rlif`, `roth`, `roth 401k`, `roth 403B`, `roth 457b`, `roth pension`, `roth profit sharing plan`, `roth thrift savings plan`, `rrif`, `rrsp`, `sarsep`, `savings`, `sep ira`, `simple ira`, `sipp`, `stock plan`, `student`, `thrift savings plan`, `tfsa`, `trust`, `ugma`, `utma`, `variable annuity` string Indicates an Item's micro-deposit-based verification or database verification status. This field is only populated when using Auth and falling back to micro-deposit or database verification. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the code. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `unsent`: The Item is pending micro-deposit verification, but Plaid has not yet sent the micro-deposit. `database_insights_pending`: The Database Auth result is pending and will be available upon Auth request. `database_insights_fail`: The Item's numbers have been verified using Plaid's data sources and have signal for being invalid and/or have no signal for being valid. Typically this indicates that the routing number is invalid, the account number does not match the account number format associated with the routing number, or the account has been reported as closed or frozen. Only returned for Auth Items created via Database Auth. `database_insights_pass`: The Item's numbers have been verified using Plaid's data sources: the routing and account number match a routing and account number of an account recognized on the Plaid network, and the account is not known by Plaid to be frozen or closed. Only returned for Auth Items created via Database Auth. `database_insights_pass_with_caution`: The Item's numbers have been verified using Plaid's data sources and have some signal for being valid: the routing and account number were not recognized on the Plaid network, but the routing number is valid and the account number is a potential valid account number for that routing number. Only returned for Auth Items created via Database Auth. `database_matched`: (deprecated) The Item has successfully been verified using Plaid's data sources. Only returned for Auth Items created via Database Match. `null` or empty string: Neither micro-deposit-based verification nor database verification are being used for the Item. Possible values: `automatically_verified`, `pending_automatic_verification`, `pending_manual_verification`, `unsent`, `manually_verified`, `verification_expired`, `verification_failed`, `database_matched`, `database_insights_pass`, `database_insights_pass_with_caution`, `database_insights_fail` string The account holder name that was used for micro-deposit and/or database verification. Only returned for Auth Items created via micro-deposit or database verification. This name was manually-entered by the user during Link, unless it was otherwise provided via the `user.legal_name` request field in `/link/token/create` for the Link session that created the Item. object Insights from performing database verification for the account. Only returned for Auth Items using Database Auth. nullable, integer Indicates the score of the name match between the given name provided during database verification (available in the [verification\_name](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-name) field if using standard Database Auth, or provided in the request if using `/auth/verify`) and matched Plaid network accounts. If defined, will be a value between 0 and 100. Will be undefined if name matching was not enabled for the database verification session or if there were no eligible Plaid network matches to compare the given name with. object Status information about the account and routing number in the Plaid network. boolean Indicates whether we found at least one matching account for the ACH account and routing number. boolean Indicates if at least one matching account for the ACH account and routing number is already verified. object Information about known ACH returns for the account and routing number. boolean Indicates whether Plaid's data sources include a known administrative ACH return for this account and routing number. string Indicator of account number format validity for institution. `valid`: indicates that the account number has a correct format for the institution. `invalid`: indicates that the account number has an incorrect format for the institution. `unknown`: indicates that there was not enough information to determine whether the format is correct for the institution. Possible values: `valid`, `invalid`, `unknown` string A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This field is currently supported only for Items at institutions that use Tokenized Account Numbers (i.e., Chase and PNC, and in May 2025 US Bank). Because these accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify an account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. In Sandbox, this field is populated for TAN-based institutions (`ins_56`, `ins_13`) as well as the OAuth Sandbox institution (`ins_127287`); in Production, it will only be populated for accounts at applicable institutions. nullable, string Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager. Possible values: `business`, `personal`, `unrecognized` \[object\] An array containing transactions from the account. Transactions are returned in reverse chronological order, with the most recent at the beginning of the array. The maximum number of transactions returned is determined by the `count` parameter. string The ID of the account in which this transaction occurred. number The settled value of the transaction, denominated in the transactions's currency, as stated in `iso_currency_code` or `unofficial_currency_code`. For all products except Income: Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. For Income endpoints, values are positive when representing income. Format: `double` nullable, string The ISO-4217 currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null. nullable, string The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The check number of the transaction. This field is only populated for check transactions. string For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). To receive information about the date that a posted transaction was initiated, see the `authorized_date` field. Format: `date` object A representation of where a transaction took place. Location data is provided only for transactions at physical locations, not for online transactions. Location data availability depends primarily on the merchant and is most likely to be populated for transactions at large retail chains; small, local businesses are less likely to have location data available. nullable, string The street address where the transaction occurred. nullable, string The city where the transaction occurred. nullable, string The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `state`. nullable, string The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called `zip`. nullable, string The ISO 3166-1 alpha-2 country code where the transaction occurred. nullable, number The latitude where the transaction occurred. Format: `double` nullable, number The longitude where the transaction occurred. Format: `double` nullable, string The merchant defined store number where the transaction occurred. deprecated, string The merchant name or transaction description. Note: While Plaid does not currently plan to remove this field, it is a legacy field that is not actively maintained. Use `merchant_name` instead for the merchant name. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, this field will always appear. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The merchant name, as enriched by Plaid from the `name` field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be `null`. nullable, string The string returned by the financial institution to describe the transaction. For transactions returned by `/transactions/sync` or `/transactions/get`, this field will only be included if the client has set `options.include_original_description` to `true`. object Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be `null`. If the `transactions` object was returned by a Transactions endpoint such as `/transactions/sync` or `/transactions/get`, the `payment_meta` key will always appear, but no data elements are guaranteed. If the `transactions` object was returned by an Assets endpoint such as `/asset_report/get/` or `/asset_report/pdf/get`, this field will only appear in an Asset Report with Insights. nullable, string The transaction reference number supplied by the financial institution. nullable, string The ACH PPD ID for the payer. nullable, string For transfers, the party that is receiving the transaction. nullable, string The party initiating a wire transfer. Will be `null` if the transaction is not a wire transfer. nullable, string For transfers, the party that is paying the transaction. nullable, string The type of transfer, e.g. 'ACH' nullable, string The name of the payment processor nullable, string The payer-supplied description of the transfer. boolean When `true`, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. Not all institutions provide pending transactions. nullable, string The ID of a posted transaction's associated pending transaction, where applicable. Not all institutions provide pending transactions. nullable, string This field is not typically populated and only relevant when dealing with sub-accounts. A sub-account most commonly exists in cases where a single account is linked to multiple cards, each with its own card number and card holder name; each card will be considered a sub-account. If the account does have sub-accounts, this field will typically be some combination of the sub-account owner's name and/or the sub-account mask. The format of this field is not standardized and will vary based on institution. string The unique ID of the transaction. Like all Plaid identifiers, the `transaction_id` is case sensitive. deprecated, string Please use the `payment_channel` field, `transaction_type` will be deprecated in the future. `digital:` transactions that took place online. `place:` transactions that were made at a physical location. `special:` transactions that relate to banks, e.g. fees or deposits. `unresolved:` transactions that do not fit into the other three types. Possible values: `digital`, `place`, `special`, `unresolved` nullable, string The URL of a logo associated with this transaction, if available. The logo will always be 100×100 pixel PNG file. nullable, string The website associated with this transaction, if available. nullable, string The date that the transaction was authorized. For posted transactions, the `date` field will indicate the posted date, but `authorized_date` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_date`, when available, is generally preferable to use over the `date` field for posted transactions, as it will generally represent the date the user actually made the transaction. Dates are returned in an [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DD` ). Format: `date` nullable, string Date and time when a transaction was authorized in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For posted transactions, the `datetime` field will indicate the posted date, but `authorized_datetime` will indicate the day the transaction was authorized by the financial institution. If presenting transactions to the user in a UI, the `authorized_datetime`, when available, is generally preferable to use over the `datetime` field for posted transactions, as it will generally represent the date the user actually made the transaction. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` nullable, string Date and time when a transaction was posted in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ( `YYYY-MM-DDTHH:mm:ssZ` ). For the date that the transaction was initiated, rather than posted, see the `authorized_datetime` field. This field is returned for select financial institutions and comes as provided by the institution. It may contain default time values (such as 00:00:00). This field is only populated in API version 2019-05-29 and later. Format: `date-time` string The channel used to make a payment. `online:` transactions that took place online. `in store:` transactions that were made at a physical location. `other:` transactions that relate to banks, e.g. fees or deposits. This field replaces the `transaction_type` field. Possible values: `online`, `in store`, `other` nullable, object Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the [taxonomy CSV file](https://plaid.com/documents/pfc-taxonomy-all.csv) for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the [migration guide](https://plaid.com/docs/transactions/pfc-migration/index.html.md) . string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string A description of how confident we are that the provided categories accurately describe the transaction intent. `VERY_HIGH`: We are more than 98% confident that this category reflects the intent of the transaction. `HIGH`: We are more than 90% confident that this category reflects the intent of the transaction. `MEDIUM`: We are moderately confident that this category reflects the intent of the transaction. `LOW`: This category may reflect the intent, but there may be other categories that are more accurate. `UNKNOWN`: We don’t know the confidence level for this category. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` nullable, string An identifier classifying the transaction type. This field is only populated for European institutions. For institutions in the US and Canada, this field is set to `null`. `adjustment:` Bank adjustment `atm:` Cash deposit or withdrawal via an automated teller machine `bank charge:` Charge or fee levied by the institution `bill payment`: Payment of a bill `cash:` Cash deposit or withdrawal `cashback:` Cash withdrawal while making a debit card purchase `cheque:` Document ordering the payment of money to another person or organization `direct debit:` Automatic withdrawal of funds initiated by a third party at a regular interval `interest:` Interest earned or incurred `purchase:` Purchase made with a debit or credit card `standing order:` Payment instructed by the account holder to a third party at a regular interval `transfer:` Transfer of money between accounts Possible values: `adjustment`, `atm`, `bank charge`, `bill payment`, `cash`, `cashback`, `cheque`, `direct debit`, `interest`, `purchase`, `standing order`, `transfer`, `null` string The URL of an icon associated with the primary personal finance category. The icon will always be 100×100 pixel PNG file. \[object\] The counterparties present in the transaction. Counterparties, such as the merchant or the financial institution, are extracted by Plaid from the raw description. string The name of the counterparty, such as the merchant or the financial institution, as extracted by Plaid from the raw description. nullable, string A unique, stable, Plaid-generated ID that maps to the counterparty. string The counterparty type. `merchant`: a provider of goods or services for purchase `financial_institution`: a financial entity (bank, credit union, BNPL, fintech) `payment_app`: a transfer or P2P app (e.g. Zelle) `marketplace`: a marketplace (e.g DoorDash, Google Play Store) `payment_terminal`: a point-of-sale payment terminal (e.g Square, Toast) `income_source`: the payer in an income transaction (e.g., an employer, client, or government agency) Possible values: `merchant`, `financial_institution`, `payment_app`, `marketplace`, `payment_terminal`, `income_source` nullable, string The website associated with the counterparty. nullable, string The URL of a logo associated with the counterparty, if available. The logo will always be 100×100 pixel PNG file. nullable, string A description of how confident we are that the provided counterparty is involved in the transaction. `VERY_HIGH`: We recognize this counterparty and we are more than 98% confident that it is involved in this transaction. `HIGH`: We recognize this counterparty and we are more than 90% confident that it is involved in this transaction. `MEDIUM`: We are moderately confident that this counterparty was involved in this transaction, but some details may differ from our records. `LOW`: We didn’t find a matching counterparty in our records, so we are returning a cleansed name parsed out of the request description. `UNKNOWN`: We don’t know the confidence level for this counterparty. nullable, object Account numbers associated with the counterparty, when available. This field is currently only filled in for select financial institutions in Europe. nullable, object Identifying information for a UK bank account via BACS. nullable, string The BACS account number for the account. nullable, string The BACS sort code for the account. nullable, object Account numbers using the International Bank Account Number and BIC/SWIFT code format. nullable, string International Bank Account Number (IBAN). Min length: `15` Max length: `34` nullable, string Bank identifier code (BIC) for this counterparty. Min length: `8` Max length: `11` nullable, string A unique, stable, Plaid-generated ID that maps to the merchant. In the case of a merchant with multiple retail locations, this field will map to the broader merchant, not a specific location or store. integer The total number of transactions available within the date range specified. If `total_transactions` is larger than the size of the `transactions` array, more transactions are available and can be fetched via manipulating the `offset` parameter. object Metadata about the Item. string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "accounts": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": 110.94, "current": 110.94, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" } ], "transactions": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "account_owner": null, "amount": 28.34, "iso_currency_code": "USD", "unofficial_currency_code": null, "check_number": null, "counterparties": [ { "name": "DoorDash", "type": "marketplace", "logo_url": "https://plaid-counterparty-logos.plaid.com/doordash_1.png", "website": "doordash.com", "entity_id": "YNRJg5o2djJLv52nBA1Yn1KpL858egYVo4dpm", "confidence_level": "HIGH" }, { "name": "Burger King", "type": "merchant", "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png", "website": "burgerking.com", "entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1", "confidence_level": "VERY_HIGH" } ], "date": "2023-09-28", "datetime": "2023-09-28T15:10:09Z", "authorized_date": "2023-09-27", "authorized_datetime": "2023-09-27T08:01:58Z", "location": { "address": null, "city": null, "region": null, "postal_code": null, "country": null, "lat": null, "lon": null, "store_number": null }, "name": "Dd Doordash Burgerkin", "merchant_name": "Burger King", "merchant_entity_id": "mVrw538wamwdm22mK8jqpp7qd5br0eeV9o4a1", "logo_url": "https://plaid-merchant-logos.plaid.com/burger_king_155.png", "website": "burgerking.com", "payment_meta": { "by_order_of": null, "payee": null, "payer": null, "payment_method": null, "payment_processor": null, "ppd_id": null, "reason": null, "reference_number": null }, "payment_channel": "online", "pending": true, "pending_transaction_id": null, "personal_finance_category": { "primary": "FOOD_AND_DRINK", "detailed": "FOOD_AND_DRINK_FAST_FOOD", "confidence_level": "VERY_HIGH" }, "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_FOOD_AND_DRINK.png", "transaction_id": "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0", "transaction_code": null, "transaction_type": "digital" }, { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "account_owner": null, "amount": 72.1, "iso_currency_code": "USD", "unofficial_currency_code": null, "check_number": null, "counterparties": [ { "name": "Walmart", "type": "merchant", "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "website": "walmart.com", "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM", "confidence_level": "VERY_HIGH" } ], "date": "2023-09-24", "datetime": "2023-09-24T11:01:01Z", "authorized_date": "2023-09-22", "authorized_datetime": "2023-09-22T10:34:50Z", "location": { "address": "13425 Community Rd", "city": "Poway", "region": "CA", "postal_code": "92064", "country": "US", "lat": 32.959068, "lon": -117.037666, "store_number": "1700" }, "name": "PURCHASE WM SUPERCENTER #1700", "merchant_name": "Walmart", "merchant_entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM", "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "website": "walmart.com", "payment_meta": { "by_order_of": null, "payee": null, "payer": null, "payment_method": null, "payment_processor": null, "ppd_id": null, "reason": null, "reference_number": null }, "payment_channel": "in store", "pending": false, "pending_transaction_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc", "personal_finance_category": { "primary": "GENERAL_MERCHANDISE", "detailed": "GENERAL_MERCHANDISE_SUPERSTORES", "confidence_level": "VERY_HIGH" }, "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png", "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje", "transaction_code": null, "transaction_type": "place" } ], "item": { "available_products": [ "balance", "identity", "investments" ], "billed_products": [ "assets", "auth", "liabilities", "transactions" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_3", "institution_name": "Chase", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook", "auth_method": "INSTANT_AUTH" }, "total_transactions": 1, "request_id": "45QSn" } ``` \=\*=\*=\*= #### /transactions/recurring/get  #### Fetch recurring transaction streams  The [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) endpoint allows developers to receive a summary of the recurring outflow and inflow streams (expenses and deposits) from a user’s checking, savings or credit card accounts. Additionally, Plaid provides key insights about each recurring stream including the category, merchant, last amount, and more. Developers can use these insights to build tools and experiences that help their users better manage cash flow, monitor subscriptions, reduce spend, and stay on track with bill payments. This endpoint is offered as an add-on to Transactions. To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/team/products) or contact your Plaid account manager. This endpoint can only be called on an Item that has already been initialized with Transactions (either during Link, by specifying it in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; or after Link, by calling [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) or [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) ). When using Recurring Transactions, for best results, make sure to use the [days\_requested](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transactions-days-requested) parameter to request at least 180 days of history when initializing Items with Transactions. Once all historical transactions have been fetched, call [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) to receive the Recurring Transactions streams and subscribe to the [RECURRING\_TRANSACTIONS\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#recurring_transactions_update) webhook. To know when historical transactions have been fetched, if you are using [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) listen for the [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#SyncUpdatesAvailableWebhook-historical-update-complete) webhook and check that the `historical_update_complete` field in the payload is `true`. If using [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , listen for the [HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#historical_update) webhook. After the initial call, you can call [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) endpoint at any point in the future to retrieve the latest summary of recurring streams. Listen to the [RECURRING\_TRANSACTIONS\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#recurring_transactions_update) webhook to be notified when new updates are available. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string The access token associated with the Item data is being requested for. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. object An optional object to be used with the request. If specified, `options` must not be `null`. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` \[string\] An optional list of `account_ids` to retrieve for the Item. Retrieves all active accounts on item if no `account_id`s are provided. Note: An error will be returned if a provided `account_id` is not associated with the Item. ```bash curl -X POST https://sandbox.plaid.com/transactions/recurring/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token":"access-production-12345678-1234-abcd-9c8f-fd5406010eee", "account_ids":[ "iRMxGT59gs5zPcE8yoHrUb0kU33jo899RCEyw", "4fPFAM3KDA2bi0ctj8SYX0KgwJQGx8A2Y6OLP", "kYcHNDmCoBDwIyD2ssgwTcZOASdvZZRjIg6I6" ] }' ``` ```node const request: TransactionsRecurringGetRequest = { access_token: accessToken, account_ids : accountIds }; try { const response = await client.transactionsRecurringGet(request); let inflowStreams = response.data.inflowStreams; let outflowStreams = response.data.outflowStreams; } catch (err) { // handle error } ``` ```python request = TransactionsRecurringGetRequest( access_token=access_token, account_ids=account_ids ) response = client.transactions_recurring_get(request) inflow_streams = response.inflow_streams outflow_streams = response.outflow_streams ``` ```ruby request = Plaid::TransactionsRecurringGetRequest.new( { access_token: access_token, account_ids: account_ids } ) response = client.transactions_recurring_get(request) inflowStreams = response.inflowStreams outflowStreams = response.outflowStreams ``` ```java TransactionsRecurringGetRequestOptions options = new TransactionsRecurringGetRequestOptions() .includePersonalFinanceCategory(true); TransactionsRecurringGetRequest request = new TransactionsRecurringGetRequest() .accessToken(accessToken) .accountIds(accountIds) .options(options); Response response = plaidClient.transactionsRecurringGet(request).execute(); List inflowStreams = new ArrayList (); inflowStreams.addAll(response.body().getInflowStreams()); List outflowStreams = new ArrayList (); outflowStreams.addAll(response.body().getOutflowStreams()); ``` ```go options := plaid.TransactionsRecurringGetRequestOptions{ IncludePersonalFinanceCategory: plaid.PtrBool(true), } request := plaid.NewTransactionsRecurringGetRequest( accessToken, account_ids, ) request.SetOptions(options) response, _, err := client.PlaidApi.TransactionsRecurringGet(ctx).TransactionsRecurringGetRequest(*request).Execute() ``` #### Response fields  \[object\] An array of depository transaction streams. string The ID of the account to which the stream belongs string A unique id for the stream string A description of the transaction stream. nullable, string The merchant associated with the transaction stream. string The posted date of the earliest transaction in the stream. Format: `date` string The posted date of the latest transaction in the stream. Format: `date` nullable, string The predicted date of the next payment. This will only be set if the next payment date can be predicted. Format: `date` string Describes the frequency of the transaction stream. `WEEKLY`: Assigned to a transaction stream that occurs approximately every week. `BIWEEKLY`: Assigned to a transaction stream that occurs approximately every 2 weeks. `SEMI_MONTHLY`: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams. `MONTHLY`: Assigned to a transaction stream that occurs approximately every month. `ANNUALLY`: Assigned to a transaction stream that occurs approximately every year. `UNKNOWN`: Assigned to a transaction stream that does not fit any of the pre-defined frequencies. Possible values: `UNKNOWN`, `WEEKLY`, `BIWEEKLY`, `SEMI_MONTHLY`, `MONTHLY`, `ANNUALLY` \[string\] An array of Plaid transaction IDs belonging to the stream, sorted by posted date. object Object with data pertaining to an amount on the transaction stream. number Represents the numerical value of an amount. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. object Object with data pertaining to an amount on the transaction stream. number Represents the numerical value of an amount. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. boolean Indicates whether the transaction stream is still live. string The current status of the transaction stream. `MATURE`: A `MATURE` recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it `MATURE` after 2 instances). `EARLY_DETECTION`: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be `EARLY_DETECTION`. `TOMBSTONED`: A stream that was previously in the `EARLY_DETECTION` status will move to the `TOMBSTONED` status when no further transactions were found at the next expected date. `UNKNOWN`: A stream is assigned an `UNKNOWN` status when none of the other statuses are applicable. Possible values: `UNKNOWN`, `MATURE`, `EARLY_DETECTION`, `TOMBSTONED` nullable, object Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the [taxonomy CSV file](https://plaid.com/documents/pfc-taxonomy-all.csv) for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the [migration guide](https://plaid.com/docs/transactions/pfc-migration/index.html.md) . string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string A description of how confident we are that the provided categories accurately describe the transaction intent. `VERY_HIGH`: We are more than 98% confident that this category reflects the intent of the transaction. `HIGH`: We are more than 90% confident that this category reflects the intent of the transaction. `MEDIUM`: We are moderately confident that this category reflects the intent of the transaction. `LOW`: This category may reflect the intent, but there may be other categories that are more accurate. `UNKNOWN`: We don’t know the confidence level for this category. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` deprecated, boolean As the ability to modify transactions streams has been discontinued, this field will always be `false`. \[object\] An array of expense transaction streams. string The ID of the account to which the stream belongs string A unique id for the stream string A description of the transaction stream. nullable, string The merchant associated with the transaction stream. string The posted date of the earliest transaction in the stream. Format: `date` string The posted date of the latest transaction in the stream. Format: `date` nullable, string The predicted date of the next payment. This will only be set if the next payment date can be predicted. Format: `date` string Describes the frequency of the transaction stream. `WEEKLY`: Assigned to a transaction stream that occurs approximately every week. `BIWEEKLY`: Assigned to a transaction stream that occurs approximately every 2 weeks. `SEMI_MONTHLY`: Assigned to a transaction stream that occurs approximately twice per month. This frequency is typically seen for inflow transaction streams. `MONTHLY`: Assigned to a transaction stream that occurs approximately every month. `ANNUALLY`: Assigned to a transaction stream that occurs approximately every year. `UNKNOWN`: Assigned to a transaction stream that does not fit any of the pre-defined frequencies. Possible values: `UNKNOWN`, `WEEKLY`, `BIWEEKLY`, `SEMI_MONTHLY`, `MONTHLY`, `ANNUALLY` \[string\] An array of Plaid transaction IDs belonging to the stream, sorted by posted date. object Object with data pertaining to an amount on the transaction stream. number Represents the numerical value of an amount. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. object Object with data pertaining to an amount on the transaction stream. number Represents the numerical value of an amount. Format: `double` nullable, string The ISO-4217 currency code of the amount. Always `null` if `unofficial_currency_code` is non-`null`. See the [currency code schema](https://plaid.com/docs/api/accounts/index.html.md#currency-code-schema) for a full listing of supported `iso_currency_code`s. nullable, string The unofficial currency code of the amount. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. boolean Indicates whether the transaction stream is still live. string The current status of the transaction stream. `MATURE`: A `MATURE` recurring stream should have at least 3 transactions and happen on a regular cadence (For Annual recurring stream, we will mark it `MATURE` after 2 instances). `EARLY_DETECTION`: When a recurring transaction first appears in the transaction history and before it fulfills the requirement of a mature stream, the status will be `EARLY_DETECTION`. `TOMBSTONED`: A stream that was previously in the `EARLY_DETECTION` status will move to the `TOMBSTONED` status when no further transactions were found at the next expected date. `UNKNOWN`: A stream is assigned an `UNKNOWN` status when none of the other statuses are applicable. Possible values: `UNKNOWN`, `MATURE`, `EARLY_DETECTION`, `TOMBSTONED` nullable, object Information describing the intent of the transaction. Most relevant for personal finance use cases, but not limited to such use cases. See the [taxonomy CSV file](https://plaid.com/documents/pfc-taxonomy-all.csv) for a full list of personal finance categories. If you are migrating to personal finance categories from the legacy categories, also refer to the [migration guide](https://plaid.com/docs/transactions/pfc-migration/index.html.md) . string A high level category that communicates the broad category of the transaction. string A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category. nullable, string A description of how confident we are that the provided categories accurately describe the transaction intent. `VERY_HIGH`: We are more than 98% confident that this category reflects the intent of the transaction. `HIGH`: We are more than 90% confident that this category reflects the intent of the transaction. `MEDIUM`: We are moderately confident that this category reflects the intent of the transaction. `LOW`: This category may reflect the intent, but there may be other categories that are more accurate. `UNKNOWN`: We don’t know the confidence level for this category. string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` deprecated, boolean As the ability to modify transactions streams has been discontinued, this field will always be `false`. string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (`YYYY-MM-DDTHH:mm:ssZ`) indicating the last time transaction streams for the given account were updated on Format: `date-time` string Indicates which version of the personal finance category taxonomy is being used. [View PFCv2 and PFCv1 taxonomies](https://plaid.com/documents/pfc-taxonomy-all.csv) . If you enabled Transactions or Enrich before December 2025 you will receive the `v1` taxonomy by default and may request `v2` by explicitly setting this field to `v2` in the request. If you enabled Transactions or Enrich on or after December 2025, you may only receive the `v2` taxonomy. Possible values: `v1`, `v2` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "updated_datetime": "2022-05-01T00:00:00Z", "inflow_streams": [ { "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje", "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nc", "category": null, "category_id": null, "description": "Platypus Payroll", "merchant_name": null, "personal_finance_category": { "primary": "INCOME", "detailed": "INCOME_WAGES", "confidence_level": "UNKNOWN" }, "first_date": "2022-02-28", "last_date": "2022-04-30", "predicted_next_date": "2022-05-15", "frequency": "SEMI_MONTHLY", "transaction_ids": [ "nkeaNrDGrhdo6c4qZWDA8ekuIPuJ4Avg5nKfw", "EfC5ekksdy30KuNzad2tQupW8WIPwvjXGbGHL", "ozfvj3FFgp6frbXKJGitsDzck5eWQH7zOJBYd", "QvdDE8AqVWo3bkBZ7WvCd7LskxVix8Q74iMoK", "uQozFPfMzibBouS9h9tz4CsyvFll17jKLdPAF" ], "average_amount": { "amount": -800, "iso_currency_code": "USD", "unofficial_currency_code": null }, "last_amount": { "amount": -1000, "iso_currency_code": "USD", "unofficial_currency_code": null }, "is_active": true, "status": "MATURE", "is_user_modified": false } ], "outflow_streams": [ { "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff", "stream_id": "no86Eox18VHMvaOVL7gPUM9ap3aR1LsAVZ5nd", "category": null, "category_id": null, "description": "ConEd Bill Payment", "merchant_name": "ConEd", "personal_finance_category": { "primary": "RENT_AND_UTILITIES", "detailed": "RENT_AND_UTILITIES_GAS_AND_ELECTRICITY", "confidence_level": "UNKNOWN" }, "first_date": "2022-02-04", "last_date": "2022-05-02", "predicted_next_date": "2022-06-02", "frequency": "MONTHLY", "transaction_ids": [ "yhnUVvtcGGcCKU0bcz8PDQr5ZUxUXebUvbKC0", "HPDnUVgI5Pa0YQSl0rxwYRwVXeLyJXTWDAvpR", "jEPoSfF8xzMClE9Ohj1he91QnvYoSdwg7IT8L", "CmdQTNgems8BT1B7ibkoUXVPyAeehT3Tmzk0l" ], "average_amount": { "amount": 85, "iso_currency_code": "USD", "unofficial_currency_code": null }, "last_amount": { "amount": 100, "iso_currency_code": "USD", "unofficial_currency_code": null }, "is_active": true, "status": "MATURE", "is_user_modified": false }, { "account_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff", "stream_id": "SrBNJZDuUMweodmPmSOeOImwsWt53ZXfJQAfC", "category": null, "category_id": null, "description": "Costco Annual Membership", "merchant_name": "Costco", "personal_finance_category": { "primary": "GENERAL_MERCHANDISE", "detailed": "GENERAL_MERCHANDISE_SUPERSTORES", "confidence_level": "UNKNOWN" }, "first_date": "2022-01-23", "last_date": "2023-01-22", "predicted_next_date": "2024-01-22", "frequency": "ANNUALLY", "transaction_ids": [ "yqEBJ72cS4jFwcpxJcDuQr94oAQ1R1lMC33D4", "Kz5Hm3cZCgpn4tMEKUGAGD6kAcxMBsEZDSwJJ" ], "average_amount": { "amount": 120, "iso_currency_code": "USD", "unofficial_currency_code": null }, "last_amount": { "amount": 120, "iso_currency_code": "USD", "unofficial_currency_code": null }, "is_active": true, "status": "MATURE", "is_user_modified": false } ], "request_id": "tbFyCEqkU775ZGG" } ``` \=\*=\*=\*= #### /transactions/refresh  #### Refresh transaction data  [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) is an optional endpoint that initiates an on-demand extraction to fetch the newest transactions for an Item. The on-demand extraction takes place in addition to the periodic extractions that automatically occur one or more times per day for any Transactions-enabled Item. The Item must already have Transactions added as a product in order to call [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) . If changes to transactions are discovered after calling [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) , Plaid will fire a webhook: for [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) users, [SYNC\_UPDATES\_AVAILABLE](https://plaid.com/docs/api/products/transactions/index.html.md#sync_updates_available) will be fired if there are any transactions updated, added, or removed. For users of both [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) and [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , [TRANSACTIONS\_REMOVED](https://plaid.com/docs/api/products/transactions/index.html.md#transactions_removed) will be fired if any removed transactions are detected, and [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/transactions/index.html.md#default_update) will be fired if any new transactions are detected. New transactions can be fetched by calling [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) or [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . Note that the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint is not supported for Capital One (`ins_128026`) non-depository accounts and will result in a `PRODUCTS_NOT_SUPPORTED` error if called on an Item that contains only non-depository accounts from that institution. As this endpoint triggers a synchronous request for fresh data, latency may be higher than for other Plaid endpoints (typically less than 10 seconds, but occasionally up to 30 seconds or more); if you encounter errors, you may find it necessary to adjust your timeout period when making requests. [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) is offered as an optional add-on to Transactions and has a separate [fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/team/products) or contact your Plaid account manager. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. required, string The access token associated with the Item data is being requested for. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. ```bash curl -X POST https://sandbox.plaid.com/transactions/refresh \ -H 'content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, }' ``` ```node const request: TransactionsRefreshRequest = { access_token: accessToken, }; try { await plaidClient.transactionsRefresh(request); } catch (error) { // handle error } ``` ```ruby request = Plaid::TransactionsRefreshRequest.new({ access_token: access_token }) response = client.transactions_refresh(request) ``` ```java TransactionsRefreshRequest request = new TransactionsRefreshRequest() .accessToken(accessToken); Response response = client() .transactionsRefresh(request) .execute(); ``` ```python request = TransactionsRefreshRequest(access_token=access_token) response = client.transactions_refresh(request) ``` ```go request := plaid.NewTransactionsRefreshRequest(accessToken) response, _, err := client.PlaidApi.TransactionsRefresh(ctx).TransactionsRefreshRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "1vwmF5TBQwiqfwP" } ``` \=\*=\*=\*= #### /categories/get  #### (Deprecated) Get legacy categories  Send a request to the [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) endpoint to get detailed information on legacy categories returned by Plaid. This endpoint does not require authentication. All implementations are recommended to [use the newer personal\_finance\_category taxonomy](https://plaid.com/docs/transactions/pfc-migration/index.html.md) instead of the legacy `category` taxonomy supported by this endpoint. #### Request fields  This endpoint or method takes an empty request body. ```bash curl -X POST https://sandbox.plaid.com/categories/get \ -H 'Content-Type: application/json' \ -d '{}' ``` ```node try { const response = await plaidClient.categoriesGet({}); const categories = response.data.categories; } catch (error) { // handle error } ``` ```python response = client.categories_get({}) categories = response['categories'] ``` ```java Response response = client().categoriesGet(new Object()).execute(); List categories = response.body().getCategories(); ``` ```ruby response = client.categories_get({}) categories = response.categories ``` ```go categoriesGetResp, _, err := client.PlaidApi.CategoriesGet(ctx).Body(nil).Execute() categories := categoriesGetResp.GetCategories() ``` #### Response fields  \[object\] An array of all of the transaction categories used by Plaid. string An identifying number for the category. `category_id` is a Plaid-specific identifier and does not necessarily correspond to merchant category codes. string `place` for physical transactions or `special` for other transactions such as bank charges. \[string\] A hierarchical array of the categories to which this `category_id` belongs. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "categories": [ { "category_id": "10000000", "group": "special", "hierarchy": [ "Bank Fees" ] }, { "category_id": "10001000", "group": "special", "hierarchy": [ "Bank Fees", "Overdraft" ] }, { "category_id": "12001000", "group": "place", "hierarchy": [ "Community", "Animal Shelter" ] } ], "request_id": "ixTBLZGvhD4NnmB" } ``` ### Webhooks  You can receive notifications via a webhook whenever there are new transactions associated with an Item, including when Plaid's initial and historical transaction pull are completed. All webhooks related to transactions have a `webhook_type` of `TRANSACTIONS`. \=\*=\*=\*= #### SYNC\_UPDATES\_AVAILABLE  Fired when an Item's transactions change. This can be due to any event resulting in new changes, such as an initial 30-day transactions fetch upon the initialization of an Item with transactions, the backfill of historical transactions that occurs shortly after, or when changes are populated from a regularly-scheduled transactions update job. It is recommended to listen for the `SYNC_UPDATES_AVAILABLE` webhook when using the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint. Note that when using [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) the older webhooks `INITIAL_UPDATE`, `HISTORICAL_UPDATE`, `DEFAULT_UPDATE`, and `TRANSACTIONS_REMOVED`, which are intended for use with [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , will also continue to be sent in order to maintain backwards compatibility. It is not necessary to listen for and respond to those webhooks when using [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . After receipt of this webhook, the new changes can be fetched for the Item from [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . Note that to receive this webhook for an Item, [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) must have been called at least once on that Item. This means that, unlike the `INITIAL_UPDATE` and `HISTORICAL_UPDATE` webhooks, it will not fire immediately upon Item creation. If [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) is called on an Item that was _not_ initialized with Transactions, the webhook will fire twice: once the first 30 days of transactions data has been fetched, and a second time when all available historical transactions data has been fetched. This webhook will fire in the Sandbox environment as it would in Production. It can also be manually triggered in Sandbox by calling [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) . #### Properties  string `TRANSACTIONS` string `SYNC_UPDATES_AVAILABLE` string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid `user_id` of the User associated with this webhook, warning, or error. boolean Indicates if initial pull information (most recent 30 days of transaction history) is available. boolean Indicates if historical pull information (maximum transaction history requested, up to 2 years) is available. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "TRANSACTIONS", "webhook_code": "SYNC_UPDATES_AVAILABLE", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "user_id": "usr_9nSp2KuZ2x4JDw", "initial_update_complete": true, "historical_update_complete": false, "environment": "production" } ``` \=\*=\*=\*= #### RECURRING\_TRANSACTIONS\_UPDATE  Fired when recurring transactions data is updated. This includes when a new recurring stream is detected or when a new transaction is added to an existing recurring stream. The `RECURRING_TRANSACTIONS_UPDATE` webhook will also fire when one or more attributes of the recurring stream changes, which is usually a result of the addition, update, or removal of transactions to the stream. After receipt of this webhook, the updated data can be fetched from [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) . #### Properties  string `TRANSACTIONS` string `RECURRING_TRANSACTIONS_UPDATE` string The `item_id` of the Item associated with this webhook, warning, or error \[string\] A list of `account_ids` for accounts that have new or updated recurring transactions data. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "TRANSACTIONS", "webhook_code": "RECURRING_TRANSACTIONS_UPDATE", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "account_ids": [ "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje", "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDff" ], "environment": "production" } ``` \=\*=\*=\*= #### INITIAL\_UPDATE  Fired when an Item's initial transaction pull is completed. Once this webhook has been fired, transaction data for the most recent 30 days can be fetched for the Item. This webhook will also be fired if account selections for the Item are updated, with `new_transactions` set to the number of net new transactions pulled after the account selection update. This webhook is intended for use with [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) ; if you are using the newer [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the `SYNC_UPDATES_AVAILABLE` webhook instead. #### Properties  string `TRANSACTIONS` string `INITIAL_UPDATE` string The error code associated with the webhook. number The number of new transactions available. string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "TRANSACTIONS", "webhook_code": "INITIAL_UPDATE", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "error": null, "new_transactions": 19, "environment": "production" } ``` \=\*=\*=\*= #### HISTORICAL\_UPDATE  Fired when an Item's historical transaction pull is completed and Plaid has prepared as much historical transaction data as possible for the Item. Once this webhook has been fired, transaction data beyond the most recent 30 days can be fetched for the Item. This webhook will also be fired if account selections for the Item are updated, with `new_transactions` set to the number of net new transactions pulled after the account selection update. This webhook is intended for use with [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) ; if you are using the newer [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the `SYNC_UPDATES_AVAILABLE` webhook instead. #### Properties  string `TRANSACTIONS` string `HISTORICAL_UPDATE` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. number The number of new transactions available string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "TRANSACTIONS", "webhook_code": "HISTORICAL_UPDATE", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "error": null, "new_transactions": 231, "environment": "production" } ``` \=\*=\*=\*= #### DEFAULT\_UPDATE  Fired when new transaction data is available for an Item. Plaid will typically check for new transaction data several times a day. This webhook is intended for use with [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) ; if you are using the newer [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the `SYNC_UPDATES_AVAILABLE` webhook instead. #### Properties  string `TRANSACTIONS` string `DEFAULT_UPDATE` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. number The number of new transactions detected since the last time this webhook was fired. string The `item_id` of the Item the webhook relates to. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "TRANSACTIONS", "webhook_code": "DEFAULT_UPDATE", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "error": null, "new_transactions": 3, "environment": "production" } ``` \=\*=\*=\*= #### TRANSACTIONS\_REMOVED  Fired when transaction(s) for an Item are deleted. The deleted transaction IDs are included in the webhook payload. Plaid will typically check for deleted transaction data several times a day. This webhook is intended for use with [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) ; if you are using the newer [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint, this webhook will still be fired to maintain backwards compatibility, but it is recommended to listen for and respond to the `SYNC_UPDATES_AVAILABLE` webhook instead. #### Properties  string `TRANSACTIONS` string `TRANSACTIONS_REMOVED` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] An array of `transaction_ids` corresponding to the removed transactions string The `item_id` of the Item associated with this webhook, warning, or error string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "TRANSACTIONS", "webhook_code": "TRANSACTIONS_REMOVED", "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb", "removed_transactions": [ "yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6", "kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no" ], "error": null, "environment": "production" } ``` --- # API - Account Linking | Plaid Docs Transfer  ========= #### API reference for Transfer account linking endpoints  For how-to guidance, see the [Transfer documentation](https://plaid.com/docs/transfer/index.html.md) . #### Account Linking  | Account Linking | | | --- | --- | | [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) | Determine RTP eligibility for a Plaid Item | | [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) | Create a transfer intent and invoke Transfer UI (Transfer UI only) | | [/transfer/intent/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentget) | Retrieve information about a transfer intent (Transfer UI only) | | [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) | Create an Item to use with Transfer from known account and routing numbers | \=\*=\*=\*= #### /transfer/capabilities/get  #### Get RTP eligibility information of a transfer  Use the [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) endpoint to determine the RTP eligibility information of an account to be used with Transfer. This endpoint works on all Transfer-capable Items, including those created by [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The Plaid `access_token` for the account that will be debited or credited. required, string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. ```node const request: TransferCapabilitiesGetRequest = { access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', }; try { const response = await client.transferCapabilitiesGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/capabilities/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", }' ``` ```ruby request = Plaid::TransferCapabilitiesGetRequest.new( { access_token: "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", account_id: "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", } ) response = client.transfer_capabilities_get(request) ``` ```java TransferCapabilitiesGetRequest request = new TransferCapabilitiesGetRequest() .accessToken("access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175") .accountId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr"); Response response = client() .transferCapabilitiesGet(request) .execute(); ``` ```python request = TransferCapabilitiesGetRequest( access_token='access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id='3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', ) response = client.transfer_capabilities_get(request) ``` ```go request := plaid.NewTransferCapabilitiesGetRequest( "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", ) response, _, err := client.PlaidApi.TransferCapabilitiesGet(ctx).TransferCapabilitiesGetRequest(*request).Execute() ``` #### Response fields  object Contains the RTP and RfP network and types supported by the linked Item's institution. object Contains the supported service types in RTP boolean When `true`, the linked Item's institution supports RTP credit transfer. Default: `false` object Contains the supported service types in RfP boolean When `true`, the linked Item's institution supports RfP debit transfer. Default: `false` nullable, string The maximum amount (decimal string with two digits of precision e.g. "10.00") for originating RfP transfers with the given institution. nullable, string The currency of the `max_amount`, e.g. "USD". string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "institution_supported_networks": { "rtp": { "credit": true }, "rfp": { "debit": true } }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/intent/create  #### Create a transfer intent object to invoke the Transfer UI  Use the [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) endpoint to generate a transfer intent object and invoke the Transfer UI. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. required, string The direction of the flow of transfer funds. `PAYMENT`: Transfers funds from an end user's account to your business account. `DISBURSEMENT`: Transfers funds from your business account to an end user's account. Possible values: `PAYMENT`, `DISBURSEMENT` string The network or rails used for the transfer. Defaults to `same-day-ach`. For transfers submitted using `ach`, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted using `same-day-ach`, the Same Day ACH cutoff is 3:00 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges. For transfers submitted using `rtp`, in the case that the account being credited does not support RTP, the transfer will be sent over ACH as long as an `ach_class` is provided in the request. If RTP isn't supported by the account and no `ach_class` is provided, the transfer will fail to be submitted. Possible values: `ach`, `same-day-ach`, `rtp` Default: `same-day-ach` required, string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. required, string A description for the underlying transfer. Maximum of 15 characters. Min length: `1` Max length: `15` string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` required, object The legal name and other information for the account holder. required, string The user's legal name. string The user's phone number. Phone number input may be validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. string The user's email address. object The address associated with the account holder. string The street number and name (i.e., "100 Market St."). string Ex. "San Francisco" string The state or province (e.g., "CA"). string The postal code (e.g., "94103"). string A two-letter country code (e.g., "US"). object The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters string The currency of the transfer amount, e.g. "USD" ```node const request: TransferIntentCreateRequest = { account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', mode: 'PAYMENT', amount: '12.34', description: 'Desc', ach_class: 'ppd', origination_account_id: '9853defc-e703-463d-86b1-dc0607a45359', user: { legal_name: 'Anne Charleston', }, }; try { const response = await client.transferIntentCreate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/intent/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "mode": "PAYMENT", "amount": "12.34", "description": "Desc", "ach_class": "ppd", "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359", "user": { "legal_name": "Anne Charleston" } }' ``` ```ruby request = Plaid::TransferIntentCreateRequest.new( { account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', mode: 'PAYMENT', amount: '12.34', ach_class: 'ppd', description: 'Desc', origination_account_id: '9853defc-e703-463d-86b1-dc0607a45359', user: { legal_name: 'Anne Charleston' } } ) response = client.transfer_intent_create(request) ``` ```java TransferUser user = new TransferUser().legalName("Anne Charleston"); TransferIntentCreateRequest request = new TransferIntentCreateRequest() .accountId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr") .mode("PAYMENT") .amount("12.34") .achClass("ppd") .description("Desc") .originationAccountId("9853defc-e703-463d-86b1-dc0607a45359") .user(user); Response response = client() .transferIntentCreate(request) .execute(); ``` ```python request = TransferIntentCreateRequest( account_id='3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', mode='PAYMENT', amount='12.34', ach_class=ACHClass('ppd'), description='Foobar', origination_account_id='9853defc-e703-463d-86b1-dc0607a45359', user=TransferUser(legal_name='Anne Charleston') ) response = client.transfer_intent_create(request) ``` ```go request := plaid.NewTransferIntentCreateRequest( "PAYMENT", "12.34", "ppd", "Desc", "9853defc-e703-463d-86b1-dc0607a45359", *plaid.NewTransferUser("Anne Charleston"), ) response, _, err := client.PlaidApi.TransferIntentCreate(ctx).TransferIntentCreateRequest(*request).Execute() ``` #### Response fields  object Represents a transfer intent within Transfer UI. string Plaid's unique identifier for the transfer intent object. string The datetime the transfer was created. This will be of the form `2006-01-02T15:04:05Z`. Format: `date-time` string The status of the transfer intent. `PENDING`: The transfer intent is pending. `SUCCEEDED`: The transfer intent was successfully created. `FAILED`: The transfer intent was unable to be created. Possible values: `PENDING`, `SUCCEEDED`, `FAILED` nullable, string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. Returned only if `account_id` was set on intent creation. string The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. string The direction of the flow of transfer funds. `PAYMENT`: Transfers funds from an end user's account to your business account. `DISBURSEMENT`: Transfers funds from your business account to an end user's account. Possible values: `PAYMENT`, `DISBURSEMENT` string The network or rails used for the transfer. Defaults to `same-day-ach`. For transfers submitted using `ach`, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted using `same-day-ach`, the Same Day ACH cutoff is 3:00 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges. For transfers submitted using `rtp`, in the case that the account being credited does not support RTP, the transfer will be sent over ACH as long as an `ach_class` is provided in the request. If RTP isn't supported by the account and no `ach_class` is provided, the transfer will fail to be submitted. Possible values: `ach`, `same-day-ach`, `rtp` Default: `same-day-ach` string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` object The legal name and other information for the account holder. string The user's legal name. nullable, string The user's phone number. nullable, string The user's email address. nullable, object The address associated with the account holder. nullable, string The street number and name (i.e., "100 Market St."). nullable, string Ex. "San Francisco" nullable, string The state or province (e.g., "CA"). nullable, string The postal code (e.g., "94103"). nullable, string A two-letter country code (e.g., "US"). string A description for the underlying transfer. Maximum of 8 characters. nullable, object The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters string The currency of the transfer amount, e.g. "USD" string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "transfer_intent": { "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "funding_account_id": "9853defc-e703-463d-86b1-dc0607a45359", "ach_class": "ppd", "amount": "12.34", "iso_currency_code": "USD", "created": "2020-08-06T17:27:15Z", "description": "Desc", "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "metadata": { "key1": "value1", "key2": "value2" }, "mode": "PAYMENT", "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359", "status": "PENDING", "user": { "address": { "street": "100 Market Street", "city": "San Francisco", "region": "CA", "postal_code": "94103", "country": "US" }, "email_address": "acharleston@email.com", "legal_name": "Anne Charleston", "phone_number": "123-456-7890" } }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/intent/get  #### Retrieve more information about a transfer intent  Use the [/transfer/intent/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentget) endpoint to retrieve more information about a transfer intent. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid's unique identifier for a transfer intent object. ```node const request: TransferIntentGetRequest = { transfer_intent_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', }; try { const response = await client.transferIntentGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/intent/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "transfer_intent_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9" }' ``` ```ruby request = Plaid::TransferIntentGetRequest.new( { transfer_intent_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9' } ) response = client.transfer_intent_get(request) ``` ```java TransferIntentGetRequest request = new TransferIntentGetRequest() .transferIntentId("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9"); Response response = client() .transferIntentGet(request) .execute(); ``` ```python request = TransferIntentGetRequest( transfer_intent_id='460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9' ) response = client.transfer_intent_get(request) ``` ```go request := plaid.NewTransferIntentGetRequest( "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", ) response, _, err := client.PlaidApi.TransferIntentGet(ctx).TransferIntentGetRequest(*request).Execute() ``` #### Response fields  object Represents a transfer intent within Transfer UI. string Plaid's unique identifier for a transfer intent object. string The datetime the transfer was created. This will be of the form `2006-01-02T15:04:05Z`. Format: `date-time` string The status of the transfer intent. `PENDING`: The transfer intent is pending. `SUCCEEDED`: The transfer intent was successfully created. `FAILED`: The transfer intent was unable to be created. Possible values: `PENDING`, `SUCCEEDED`, `FAILED` nullable, string Plaid's unique identifier for the transfer created through the UI. Returned only if the transfer was successfully created. Null value otherwise. nullable, object The reason for a failed transfer intent. Returned only if the transfer intent status is `failed`. Null otherwise. string A broad categorization of the error. string A code representing the reason for a failed transfer intent (i.e., an API error or the authorization being declined). string A human-readable description of the code associated with a failed transfer intent. nullable, string A decision regarding the proposed transfer. `APPROVED` – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The `decision_rationale` field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended (i.e., use Link in update mode to re-authenticate your user when `decision_rationale.code` is `ITEM_LOGIN_REQUIRED`). Refer to the `code` field in the `decision_rationale` object for details. `DECLINED` – Plaid reviewed the proposed transfer and declined processing. Refer to the `code` field in the `decision_rationale` object for details. Possible values: `APPROVED`, `DECLINED` nullable, object The rationale for Plaid's decision regarding a proposed transfer. It is always set for `declined` decisions, and may or may not be null for `approved` decisions. string A code representing the rationale for approving or declining the proposed transfer. If the `rationale_code` is `null`, the transfer passed the authorization check. Any non-`null` value for an `approved` transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an `approved` transfer are: `MANUALLY_VERIFIED_ITEM` – Item created via a manual entry flow (i.e. Same Day Micro-deposit, Instant Micro-deposit, or database-based verification), limited information available. `ITEM_LOGIN_REQUIRED` – Unable to collect the account information due to Item staleness. Can be resolved by using Link and setting [transfer.authorization\_id](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transfer-authorization-id) in the request to `/link/token/create`. `MIGRATED_ACCOUNT_ITEM` - Item created via `/transfer/migrate_account` endpoint, limited information available. `ERROR` – Unable to collect the account information due to an unspecified error. The following codes indicate that the authorization decision was `declined`: `NSF` – Transaction likely to result in a return due to insufficient funds. `RISK` - Transaction is high-risk. `TRANSFER_LIMIT_REACHED` - One or several transfer limits are reached, e.g. monthly transfer limit. Check the accompanying `description` field to understand which limit has been reached. Possible values: `NSF`, `RISK`, `TRANSFER_LIMIT_REACHED`, `MANUALLY_VERIFIED_ITEM`, `ITEM_LOGIN_REQUIRED`, `PAYMENT_PROFILE_LOGIN_REQUIRED`, `ERROR`, `MIGRATED_ACCOUNT_ITEM`, `null` string A human-readable description of the code associated with a transfer approval or transfer decline. nullable, string The Plaid `account_id` for the account that will be debited or credited. Returned only if `account_id` was set on intent creation. string The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. string The direction of the flow of transfer funds. `PAYMENT`: Transfers funds from an end user's account to your business account. `DISBURSEMENT`: Transfers funds from your business account to an end user's account. Possible values: `PAYMENT`, `DISBURSEMENT` string The network or rails used for the transfer. Defaults to `same-day-ach`. For transfers submitted using `ach`, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted using `same-day-ach`, the Same Day ACH cutoff is 3:00 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges. For transfers submitted using `rtp`, in the case that the account being credited does not support RTP, the transfer will be sent over ACH as long as an `ach_class` is provided in the request. If RTP isn't supported by the account and no `ach_class` is provided, the transfer will fail to be submitted. Possible values: `ach`, `same-day-ach`, `rtp` Default: `same-day-ach` string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` object The legal name and other information for the account holder. string The user's legal name. nullable, string The user's phone number. nullable, string The user's email address. nullable, object The address associated with the account holder. nullable, string The street number and name (i.e., "100 Market St."). nullable, string Ex. "San Francisco" nullable, string The state or province (e.g., "CA"). nullable, string The postal code (e.g., "94103"). nullable, string A two-letter country code (e.g., "US"). string A description for the underlying transfer. Maximum of 8 characters. nullable, object The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters string The currency of the transfer amount, e.g. "USD" string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "transfer_intent": { "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "funding_account_id": "9853defc-e703-463d-86b1-dc0607a45359", "ach_class": "ppd", "amount": "12.34", "iso_currency_code": "USD", "authorization_decision": "APPROVED", "authorization_decision_rationale": null, "created": "2019-12-09T17:27:15Z", "description": "Desc", "failure_reason": null, "guarantee_decision": null, "guarantee_decision_rationale": null, "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "metadata": { "key1": "value1", "key2": "value2" }, "mode": "DISBURSEMENT", "origination_account_id": "9853defc-e703-463d-86b1-dc0607a45359", "status": "SUCCEEDED", "transfer_id": "590ecd12-1dcc-7eae-4ad6-c28d1ec90df2", "user": { "address": { "street": "123 Main St.", "city": "San Francisco", "region": "California", "postal_code": "94053", "country": "US" }, "email_address": "acharleston@email.com", "legal_name": "Anne Charleston", "phone_number": "510-555-0128" } }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/migrate\_account  #### Migrate account into Transfers  As an alternative to adding Items via Link, you can also use the [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) endpoint to migrate previously-verified account and routing numbers to Plaid Items. This endpoint is also required when adding an Item for use with wire transfers; if you intend to create wire transfers on this account, you must provide `wire_routing_number`. Note that Items created in this way are not compatible with endpoints for other products, such as [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) , and can only be used with Transfer endpoints. If you require access to other endpoints, create the Item through Link instead. Access to [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) is not enabled by default; to obtain access, contact your Plaid Account Manager or [Support](https://dashboard.plaid.com/support) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The user's account number. required, string The user's routing number. string The user's wire transfer routing number. This is the ABA number; for some institutions, this may differ from the ACH number used in `routing_number`. This field must be set for the created item to be eligible for wire transfers. required, string The type of the bank account (`checking` or `savings`). ```node const request: TransferMigrateAccountRequest = { account_number: '100000000', routing_number: '121122676', account_type: 'checking', }; try { const response = await plaidClient.transferMigrateAccount(request); const access_token = response.data.access_token; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/migrate_account \ -H 'content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "account_number": String, "routing_number": String, "account_type": String }' ``` ```ruby request = Plaid::TransferMigrateAccountRequest.new( { account_number: "100000000", routing_number: "121122676", account_type: "checking", } ) response = client.transfer_migrate_account(request) access_token = response.access_token ``` ```java TransferMigrateAccountRequest request = new TransferMigrateAccountRequest() .accountNumber("100000000") .routingNumber("121122676") .accountType("checking"); Response response = client() .transferMigrateAccount(request) .execute(); String accessToken = response.body().getAccessToken(); ``` ```python request = TransferMigrateAccountRequest( account_number = '100000000', routing_number = '121122676', account_type = 'checking' ) response = client.transfer_migrate_account(request) access_token = response['access_token'] ``` ```go request := plaid.NewTransferMigrateAccountRequest( "ACCOUNT_NUMBER", // 100000000 "ROUTING_NUMBER", // 121122676 "ACCOUNT_TYPE", // checking ) response, _, err := client.PlaidApi.TransferMigrateAccount(ctx).TransferMigrateAccountRequest(*request).Execute() ``` #### Response fields  string The Plaid `access_token` for the newly created Item. string The Plaid `account_id` for the newly created Item. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "access_token": "access-sandbox-435beced-94e8-4df3-a181-1dde1cfa19f0", "account_id": "zvyDgbeeDluZ43AJP6m5fAxDlgoZXDuoy5gjN", "request_id": "mdqfuVxeoza6mhu" } ``` --- # API - Transfer | Plaid Docs Transfer  ========= #### API reference for Transfer endpoints and webhooks  For how-to guidance, see the [Transfer documentation](https://plaid.com/docs/transfer/index.html.md) . | Initiating Transfers | | | --- | --- | | [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) | Create a transfer authorization | | [/transfer/authorization/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcancel) | Cancel a transfer authorization | | [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) | Create a transfer | | [/transfer/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercancel) | Cancel a transfer | | Reading Transfers | | | --- | --- | | [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) | Retrieve information about a transfer | | [/transfer/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferlist) | Retrieve a list of transfers and their statuses | | [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) | Retrieve a list of transfer events | | [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) | Sync transfer events | | [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) | Retrieve information about a sweep | | [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) | Retrieve a list of sweeps | | Account Linking | | | --- | --- | | [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) | Determine RTP eligibility for a Plaid Item | | [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) | Create a transfer intent and invoke Transfer UI (Transfer UI only) | | [/transfer/intent/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentget) | Retrieve information about a transfer intent (Transfer UI only) | | [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) | Create an Item to use with Transfer from known account and routing numbers | | Recurring Transfers | | | --- | --- | | [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) | Create a recurring transfer | | [/transfer/recurring/cancel](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcancel) | Cancel a recurring transfer | | [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) | Retrieve information about a recurring transfer | | [/transfer/recurring/list](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringlist) | Retrieve a list of recurring transfers | | Refunds | | | --- | --- | | [/transfer/refund/create](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcreate) | Create a refund for a transfer | | [/transfer/refund/cancel](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcancel) | Cancel a refund | | [/transfer/refund/get](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundget) | Retrieve information about a refund | | Transfer for Platforms | | | --- | --- | | [/transfer/platform/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformoriginatorcreate) | Pass transfer specific onboarding info for the originator | | [/transfer/platform/person/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformpersoncreate) | Create each individual who is a beneficial owner or control person of the business | | [/transfer/platform/requirement/submit](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformrequirementsubmit) | Pass additional data Plaid needs to make an onboarding decision for the originator | | [/transfer/platform/document/submit](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformdocumentsubmit) | Submit documents Plaid needs to verify information about the originator | | [/transfer/originator/get](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorget) | Get the status of an originator's onboarding | | [/transfer/originator/list](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorlist) | Get the status of all originators' onboarding | | [/transfer/originator/funding\_account/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorfunding_accountcreate) | Create a new funding account for an originator | | Plaid Ledger | | | --- | --- | | [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) | Deposit funds into a ledger balance held with Plaid | | [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) | Move available balance between platform and its originator | | [/transfer/ledger/get](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerget) | Retrieve information about the ledger balance held with Plaid | | [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) | Withdraw funds from a ledger balance held with Plaid | | [/transfer/ledger/event/list](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgereventlist) | Retrieve a list of ledger balance events | | Program Metrics | | | --- | --- | | [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) | Get transfer product usage metrics | | [/transfer/configuration/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transferconfigurationget) | Get transfer product configuration | | Sandbox | | | --- | --- | | [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) | Simulate a transfer event | | [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) | Simulate a refund event | | [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) | Simulate a transfer webhook | | [/sandbox/transfer/ledger/deposit/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerdepositsimulate) | Simulate a deposit sweep event | | [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) | Simulate converting pending balance into available balance | | [/sandbox/transfer/ledger/withdraw/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerwithdrawsimulate) | Simulate a withdrawal sweep event | | [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) | Create a test clock | | [/sandbox/transfer/test\_clock/advance](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockadvance) | Advance a test clock | | [/sandbox/transfer/test\_clock/get](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockget) | Retrieve information about a test clock | | [/sandbox/transfer/test\_clock/list](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clocklist) | Retrieve a list of test clocks | | Webhooks | | | --- | --- | | [TRANSFER\_EVENTS\_UPDATE](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfer_events_update) | New transfer events available | | [RECURRING\_CANCELLED](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_cancelled) | A recurring transfer has been cancelled by Plaid | | [RECURRING\_NEW\_TRANSFER](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_new_transfer) | A new transfer of a recurring transfer has been originated | | [RECURRING\_TRANSFER\_SKIPPED](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_transfer_skipped) | An instance of a scheduled recurring transfer could not be created | --- # API - Initiating Transfers | Plaid Docs Initiating transfers  ===================== #### API reference for Transfer initiation endpoints  For how-to guidance, see the [Transfer creation documentation](https://plaid.com/docs/transfer/creating-transfers/index.html.md) . | Initiating Transfers | | | --- | --- | | [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) | Create a transfer authorization | | [/transfer/authorization/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcancel) | Cancel a transfer authorization | | [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) | Create a transfer | | [/transfer/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercancel) | Cancel a transfer | \=\*=\*=\*= #### /transfer/authorization/create  #### Create a transfer authorization  Use the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) endpoint to authorize a transfer. This endpoint must be called prior to calling [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) . The transfer authorization will expire if not used after one hour. (You can contact your account manager to change the default authorization lifetime.) There are four possible outcomes to calling this endpoint: * If the `authorization.decision` in the response is `declined`, the proposed transfer has failed the risk check and you cannot proceed with the transfer. * If the `authorization.decision` is `user_action_required`, additional user input is needed, usually to fix a broken bank connection, before Plaid can properly assess the risk. You need to launch Link in update mode to complete the required user action. When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to get a new Link token, instead of providing `access_token` in the request, you should set [transfer.authorization\_id](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transfer-authorization-id) as the `authorization.id`. After the Link flow is completed, you may re-attempt the authorization. * If the `authorization.decision` is `approved`, and the `authorization.rationale_code` is `null`, the transfer has passed the risk check and you can proceed to call [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) . * If the `authorization.decision` is `approved` and the `authorization.rationale_code` is non-`null`, the risk check could not be run: you may proceed with the transfer, but should perform your own risk evaluation. For more details, see the response schema. In Plaid's Sandbox environment the decisions will be returned as follows: * To approve a transfer with `null` rationale code, make an authorization request with an `amount` less than the available balance in the account. * To approve a transfer with the rationale code `MANUALLY_VERIFIED_ITEM`, create an Item in Link through the [Same Day Micro-deposits flow](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-same-day-micro-deposits) . * To get an authorization decision of `user_action_required`, [reset the login for an Item](https://plaid.com/docs/sandbox/index.html.md#item_login_required) . * To decline a transfer with the rationale code `NSF`, the available balance on the account must be less than the authorization `amount`. See [Create Sandbox test data](https://plaid.com/docs/sandbox/user-custom/index.html.md) for details on how to customize data in Sandbox. * To decline a transfer with the rationale code `RISK`, the available balance on the account must be exactly $0. See [Create Sandbox test data](https://plaid.com/docs/sandbox/user-custom/index.html.md) for details on how to customize data in Sandbox. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The Plaid `access_token` for the account that will be debited or credited. required, string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. string Specify which ledger balance should be used to fund the transfer. You can find a list of `ledger_id`s in the Accounts page of your Plaid Dashboard. If this field is left blank, this will default to id of the default ledger balance. required, string The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `debit`, `credit` required, string The network or rails used for the transfer. For transfers submitted as `ach` or `same-day-ach`, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted as `same-day-ach`, the Same Day ACH cutoff is 3:00 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail. For transfers submitted as `rtp`, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as `rtp` and the counterparty account is not eligible for RTP, the `/transfer/authorization/create` request will fail with an `INVALID_FIELD` error code. To pre-check to determine whether a counterparty account can support RTP, call `/transfer/capabilities/get` before calling `/transfer/authorization/create`. Wire transfers are currently in early availability. To request access to `wire` as a payment network, contact your Account Manager. For transfers submitted as `wire`, the `type` must be `credit`; wire debits are not supported. The cutoff to submit a wire payment is 6:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail. Possible values: `ach`, `same-day-ach`, `rtp`, `wire` required, string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` object Information specific to wire transfers. string Additional information from the wire originator to the beneficiary. Max 140 characters. string The fee amount deducted from the original transfer during a wire return, if applicable. required, object The legal name and other information for the account holder. If the account has multiple account holders, provide the information for the account holder on whose behalf the authorization is being requested. The `user.legal_name` field is required. Other fields are not currently used and are present to support planned future functionality. required, string The user's legal name. If the user is a business, provide the business name. string The user's phone number. string The user's email address. object The address associated with the account holder. string The street number and name (i.e., "100 Market St."). string Ex. "San Francisco" string The state or province (e.g., "CA"). string The postal code (e.g., "94103"). string A two-letter country code (e.g., "US"). object Information about the device being used to initiate the authorization. These fields are not currently incorporated into the risk check. string The IP address of the device being used to initiate the authorization. string The user agent of the device being used to initiate the authorization. string The currency of the transfer amount. The default value is "USD". string A random key provided by the client, per unique authorization, which expires after 48 hours. Maximum of 50 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create an authorization fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single authorization is created. Idempotency does not apply to authorizations whose decisions are `user_action_required`. Therefore you may re-attempt the authorization after completing the required user action without changing `idempotency_key`. This idempotency key expires after 48 hours, after which the same key can be reused. Failure to provide this key may result in duplicate charges. Max length: `50` boolean If the end user is initiating the specific transfer themselves via an interactive UI, this should be `true`; for automatic recurring payments where the end user is not actually initiating each individual transfer, it should be `false`. This field is not currently used and is present to support planned future functionality. string The Plaid client ID that is the originator of this transfer. Only needed if creating transfers on behalf of another client as a [Platform customer](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) . string Plaid’s unique identifier for a test clock. This field may only be used when using `sandbox` environment. If provided, the `authorization` is created at the `virtual_time` on the provided test clock. string The key of the Ruleset for the transaction. This feature is currently in closed beta; to request access, contact your account manager. ```node const request: TransferAuthorizationCreateRequest = { access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', type: 'debit', network: 'ach', amount: '12.34', ach_class: 'ppd', user: { legal_name: 'Anne Charleston', }, }; try { const response = await client.transferAuthorizationCreate(request); const authorizationId = response.data.authorization.id; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/authorization/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "type": "debit", "network": "ach", "amount": "12.34", "ach_class": "ppd", "user": { "legal_name": "Anne Charleston" } }' ``` ```ruby request = Plaid::TransferAuthorizationCreateRequest.new( { access_token: "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", account_id: "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", type: Plaid::TransferType::DEBIT, network: Plaid::TransferNetwork::ACH, amount: "12.34", ach_class: "ppd", user: { legal_name: "Anne Charleston" } } ) response = client.transfer_authorization_create(request) transfer = response.transfer ``` ```java TransferAuthorizationUserInRequest user = new TransferAuthorizationUserInRequest().legalName("Anne Charleston"); TransferAuthorizationCreateRequest request = new TransferAuthorizationCreateRequest() .accessToken("access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175") .accountId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr") .type("debit") .network("ach") .amount("12.34") .user(user) .achClass("ppd"); Response response = client() .transferAuthorizationCreate(request) .execute(); Transfer transfer = response.body().getTransfer(); ``` ```python request = TransferAuthorizationCreateRequest( access_token='access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id='3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', type=TransferType('debit'), network=TransferNetwork('ach'), amount='12.34', user=TransferAuthorizationUserInRequest(legal_name='Anne Charleston'), ach_class=ACHClass('ppd') ) response = client.transfer_authorization_create(request) transfer = response['transfer'] ``` ```go request := plaid.NewTransferAuthorizationCreateRequest( accessToken, accountID, plaid.TRANSFERTYPE_DEBIT, plaid.TRANSFERNETWORK_ACH, "12.34", *plaid.NewTransferAuthorizationUserInRequest("Anne Charleston"), ) request.SetAchClass(plaid.ACHCLASS_PPD) response, _, err := client.PlaidApi.TransferAuthorizationCreate(ctx).TransferAuthorizationCreateRequest(*request).Execute() ``` #### Response fields  object Contains the authorization decision for a proposed transfer. string Plaid’s unique identifier for a transfer authorization. string The datetime representing when the authorization was created, in the format `2006-01-02T15:04:05Z`. Format: `date-time` string A decision regarding the proposed transfer. `approved` – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The `decision_rationale` field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended. Refer to the `code` field in the `decision_rationale` object for details. `declined` – Plaid reviewed the proposed transfer and declined processing. Refer to the `code` field in the `decision_rationale` object for details. `user_action_required` – An action is required before Plaid can assess the transfer risk and make a decision. The most common scenario is to update authentication for an Item. To complete the required action, initialize Link by setting `transfer.authorization_id` in the request of `/link/token/create`. After Link flow is completed, you may re-attempt the authorization request. For `guarantee` requests, `approved` indicates the transfer is eligible for Plaid's guarantee, and `declined` indicates Plaid will not provide guarantee coverage for the transfer. `user_action_required` indicates you should follow the above guidance before re-attempting. Possible values: `approved`, `declined`, `user_action_required` nullable, object The rationale for Plaid's decision regarding a proposed transfer. It is always set for `declined` decisions, and may or may not be null for `approved` decisions. string A code representing the rationale for approving or declining the proposed transfer. If the `rationale_code` is `null`, the transfer passed the authorization check. Any non-`null` value for an `approved` transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an `approved` transfer are: `MANUALLY_VERIFIED_ITEM` – Item created via a manual entry flow (i.e. Same Day Micro-deposit, Instant Micro-deposit, or database-based verification), limited information available. `ITEM_LOGIN_REQUIRED` – Unable to collect the account information due to Item staleness. Can be resolved by using Link and setting [transfer.authorization\_id](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transfer-authorization-id) in the request to `/link/token/create`. `MIGRATED_ACCOUNT_ITEM` - Item created via `/transfer/migrate_account` endpoint, limited information available. `ERROR` – Unable to collect the account information due to an unspecified error. The following codes indicate that the authorization decision was `declined`: `NSF` – Transaction likely to result in a return due to insufficient funds. `RISK` - Transaction is high-risk. `TRANSFER_LIMIT_REACHED` - One or several transfer limits are reached, e.g. monthly transfer limit. Check the accompanying `description` field to understand which limit has been reached. Possible values: `NSF`, `RISK`, `TRANSFER_LIMIT_REACHED`, `MANUALLY_VERIFIED_ITEM`, `ITEM_LOGIN_REQUIRED`, `PAYMENT_PROFILE_LOGIN_REQUIRED`, `ERROR`, `MIGRATED_ACCOUNT_ITEM`, `null` string A human-readable description of the code associated with a transfer approval or transfer decline. object Details regarding the proposed transfer. string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` string The Plaid `account_id` for the account that will be debited or credited. nullable, string The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `debit`, `credit` object The legal name and other information for the account holder. string The user's legal name. nullable, string The user's phone number. nullable, string The user's email address. nullable, object The address associated with the account holder. nullable, string The street number and name (i.e., "100 Market St."). nullable, string Ex. "San Francisco" nullable, string The state or province (e.g., "CA"). nullable, string The postal code (e.g., "94103"). nullable, string A two-letter country code (e.g., "US"). string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. string The network or rails used for the transfer. nullable, object Information specific to wire transfers. nullable, string Additional information from the wire originator to the beneficiary. Max 140 characters. nullable, string The fee amount deducted from the original transfer during a wire return, if applicable. string The currency of the transfer amount. The default value is "USD". nullable, string The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a [Platform customer](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) . deprecated, nullable, string This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023. Specifies the source of funds for the transfer. Only valid for `credit` transfers, and defaults to `sweep` if not specified. This field is not specified for `debit` transfers. `sweep` - Sweep funds from your funding account `prefunded_rtp_credits` - Use your prefunded RTP credit balance with Plaid `prefunded_ach_credits` - Use your prefunded ACH credit balance with Plaid Possible values: `sweep`, `prefunded_rtp_credits`, `prefunded_ach_credits`, `null` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "authorization": { "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "created": "2020-08-06T17:27:15Z", "decision": "approved", "decision_rationale": null, "guarantee_decision": null, "guarantee_decision_rationale": null, "payment_risk": null, "proposed_transfer": { "ach_class": "ppd", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "type": "credit", "user": { "legal_name": "Anne Charleston", "phone_number": "510-555-0128", "email_address": "acharleston@email.com", "address": { "street": "123 Main St.", "city": "San Francisco", "region": "CA", "postal_code": "94053", "country": "US" } }, "amount": "12.34", "network": "ach", "iso_currency_code": "USD", "origination_account_id": "", "originator_client_id": null, "credit_funds_source": "sweep" } }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/authorization/cancel  #### Cancel a transfer authorization  Use the [/transfer/authorization/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcancel) endpoint to cancel a transfer authorization. A transfer authorization is eligible for cancellation if it has not yet been used to create a transfer. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a transfer authorization. ```bash curl -X POST https://sandbox.plaid.com/transfer/authorization/cancel \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "authorization_id": "123004561178933" }' ``` ```python request = TransferAuthorizationCancelRequest(authorization_id='123004561178933') response = client.transfer_authorization_cancel(request) ``` ```node const request: TransferAuthorizationCancelRequest = { authorization_id: '123004561178933', }; try { const response = await plaidClient.transferAuthorizationCancel(request); const request_id = response.data.request_id; } catch (error) { // handle error } ``` ```java TransferAuthorizationCancelRequest request = new TransferAuthorizationCancelRequest() .authorizationId("123004561178933"); Response response = client() .transferAuthorizationCancel(request) .execute(); ``` ```ruby request = Plaid::TransferAuthorizationCancelRequest.new({ authorization_id: '123004561178933' }) response = client.transfer_authorization_cancel(request) ``` ```go request := plaid.NewTransferAuthorizationCancelRequest( "123004561178933" ) response, _, err := client.PlaidApi.TransferAuthorizationCancel(ctx).TransferAuthorizationCancelRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/create  #### Create a transfer  Use the [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) endpoint to initiate a new transfer. This endpoint is retryable and idempotent; if a transfer with the provided `transfer_id` has already been created, it will return the transfer details without creating a new transfer. A transfer may still be created if a 500 error is returned; to detect this scenario, use [Transfer events](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The Plaid `access_token` for the account that will be debited or credited. required, string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. required, string Plaid’s unique identifier for a transfer authorization. This parameter also serves the purpose of acting as an idempotency identifier. string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. required, string The transfer description, maximum of 15 characters (RTP transactions) or 10 characters (ACH transactions). Should represent why the money is moving, not your company name. For recommendations on setting the `description` field to avoid ACH returns, see [Description field recommendations](https://www.plaid.com/docs/transfer/creating-transfers/#description-field-recommendations) . If reprocessing a returned transfer, the `description` field must be `"Retry 1"` or `"Retry 2"`. You may retry a transfer up to 2 times, within 180 days of creating the original transfer. Only transfers that were returned with code `R01` or `R09` may be retried. Max length: `15` object The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters string Plaid’s unique identifier for a test clock. This field may only be used when using `sandbox` environment. If provided, the `transfer` is created at the `virtual_time` on the provided `test_clock`. string The amount to deduct from `transfer.amount` and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be value greater than 0 and less than or equal to the `transfer.amount`. ```bash curl -X POST https://sandbox.plaid.com/transfer/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "authorization_id": "231h012308h3101z21909sw", "description": "Payment" }' ``` ```python request = TransferCreateRequest( access_token='access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id='3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', authorization_id='231h012308h3101z21909sw', description='payment', ) response = client.transfer_create(request) transfer = response['transfer'] ``` ```node const request: TransferCreateRequest = { access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', description: 'payment', authorization_id: '231h012308h3101z21909sw', }; try { const response = await client.transferCreate(request); const transfer = response.data.transfer; } catch (error) { // handle error } ``` ```java TransferUser user = new TransferUser().legalName("Anne Charleston"); TransferCreateRequest request = new TransferCreateRequest() .accessToken("access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175") .accountId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr") .authorizationId("231h012308h3101z21909sw") .description("payment"); Response response = client() .transferCreate(request) .execute(); Transfer transfer = response.body().getTransfer(); ``` ```ruby request = Plaid::TransferCreateRequest.new( { access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', authorization_id: '231h012308h3101z21909sw', description: 'payment', } ) response = client.transfer_create(request) transfer = response.transfer ``` ```go request := plaid.NewTransferCreateRequest( "231h012308h3101z21909sw", "payment", ) request.SetAccessToken(accessToken); request.SetAccountId(accountID); response, _, err := client.PlaidApi.TransferCreate(ctx).TransferCreateRequest(*request).Execute() ``` #### Response fields  object Represents a transfer within the Transfers API. string Plaid’s unique identifier for a transfer. string Plaid’s unique identifier for a transfer authorization. string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. nullable, string The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `debit`, `credit` object The legal name and other information for the account holder. string The user's legal name. nullable, string The user's phone number. nullable, string The user's email address. nullable, object The address associated with the account holder. nullable, string The street number and name (i.e., "100 Market St."). nullable, string Ex. "San Francisco" nullable, string The state or province (e.g., "CA"). nullable, string The postal code (e.g., "94103"). nullable, string A two-letter country code (e.g., "US"). string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. string The description of the transfer. string The datetime when this transfer was created. This will be of the form `2006-01-02T15:04:05Z` Format: `date-time` string The status of the transfer. `pending`: A new transfer was created; it is in the pending state. `posted`: The transfer has been successfully submitted to the payment network. `settled`: The transfer was successfully completed by the payment network. Note that funds from received debits are not available to be moved out of the Ledger until the transfer reaches `funds_available` status. For credit transactions, `settled` means the funds have been delivered to the receiving bank account. This is the terminal state of a successful credit transfer. `funds_available`: Funds from the transfer have been released from hold and applied to the ledger's available balance. (Only applicable to ACH debits.) This is the terminal state of a successful debit transfer. `cancelled`: The transfer was cancelled by the client. This is the terminal state of a cancelled transfer. `failed`: The transfer failed, no funds were moved. This is the terminal state of a failed transfer. `returned`: A posted transfer was returned. This is the terminal state of a returned transfer. Possible values: `pending`, `posted`, `settled`, `funds_available`, `cancelled`, `failed`, `returned` nullable, string The status of the sweep for the transfer. `unswept`: The transfer hasn't been swept yet. `swept`: The transfer was swept to the sweep account. `swept_settled`: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. `return_swept`: The transfer was returned, funds were pulled back or pushed back to the sweep account. `null`: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept) Possible values: `null`, `unswept`, `swept`, `swept_settled`, `return_swept` string The network or rails used for the transfer. For transfers submitted as `ach` or `same-day-ach`, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted as `same-day-ach`, the Same Day ACH cutoff is 3:00 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail. For transfers submitted as `rtp`, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as `rtp` and the counterparty account is not eligible for RTP, the `/transfer/authorization/create` request will fail with an `INVALID_FIELD` error code. To pre-check to determine whether a counterparty account can support RTP, call `/transfer/capabilities/get` before calling `/transfer/authorization/create`. Wire transfers are currently in early availability. To request access to `wire` as a payment network, contact your Account Manager. For transfers submitted as `wire`, the `type` must be `credit`; wire debits are not supported. The cutoff to submit a wire payment is 6:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail. Possible values: `ach`, `same-day-ach`, `rtp`, `wire` nullable, object Information specific to wire transfers. nullable, string Additional information from the wire originator to the beneficiary. Max 140 characters. nullable, string The fee amount deducted from the original transfer during a wire return, if applicable. boolean When `true`, you can still cancel this transfer. nullable, object The failure reason if the event type for a transfer is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the transfer status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . string A human-readable description of the reason for the failure or reversal. nullable, object The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters string The currency of the transfer amount, e.g. "USD" nullable, string The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD. Format: `date` nullable, string The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD. Format: `date` deprecated, nullable, string Deprecated for Plaid Ledger clients, use `expected_funds_available_date` instead. Format: `date` nullable, string The expected date when funds from a transfer will be made available and can be withdrawn from the associated ledger balance, assuming the debit does not return before this date. If the transfer does return before this date, this field will be null. Only applies to debit transfers. This will be of the form YYYY-MM-DD. Format: `date` nullable, string The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a [Platform customer](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) . \[object\] A list of refunds associated with this transfer. string Plaid’s unique identifier for a refund. string The ID of the transfer to refund. string The amount of the refund (decimal string with two digits of precision e.g. "10.00"). string The status of the refund. `pending`: A new refund was created; it is in the pending state. `posted`: The refund has been successfully submitted to the payment network. `settled`: Credits have been refunded to the Plaid linked account. `cancelled`: The refund was cancelled by the client. `failed`: The refund has failed. `returned`: The refund was returned. Possible values: `pending`, `posted`, `cancelled`, `failed`, `settled`, `returned` nullable, object The failure reason if the event type for a refund is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the refund status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the refund status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . This field is deprecated in favor of the more versatile `failure_code`, which encompasses non-ACH failure codes as well. string A human-readable description of the reason for the failure or reversal. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The datetime when this refund was created. This will be of the form `2006-01-02T15:04:05Z` Format: `date-time` nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. nullable, string The id of the recurring transfer if this transfer belongs to a recurring transfer. \[object\] The expected sweep settlement schedule of this transfer, assuming this transfer is not `returned`. Only applies to ACH debit transfers. string The settlement date of a sweep for this transfer. Format: `date` string The accumulated amount that has been swept by `sweep_settlement_date`. deprecated, nullable, string This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023. Specifies the source of funds for the transfer. Only valid for `credit` transfers, and defaults to `sweep` if not specified. This field is not specified for `debit` transfers. `sweep` - Sweep funds from your funding account `prefunded_rtp_credits` - Use your prefunded RTP credit balance with Plaid `prefunded_ach_credits` - Use your prefunded ACH credit balance with Plaid Possible values: `sweep`, `prefunded_rtp_credits`, `prefunded_ach_credits`, `null` string The amount to deduct from `transfer.amount` and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be value greater than 0 and less than or equal to the `transfer.amount`. nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "transfer": { "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586", "ach_class": "ppd", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "type": "credit", "user": { "legal_name": "Anne Charleston", "phone_number": "510-555-0128", "email_address": "acharleston@email.com", "address": { "street": "123 Main St.", "city": "San Francisco", "region": "CA", "postal_code": "94053", "country": "US" } }, "amount": "12.34", "description": "payment", "created": "2020-08-06T17:27:15Z", "refunds": [], "status": "pending", "network": "ach", "cancellable": true, "guarantee_decision": null, "guarantee_decision_rationale": null, "failure_reason": null, "metadata": { "key1": "value1", "key2": "value2" }, "origination_account_id": "", "iso_currency_code": "USD", "standard_return_window": "2023-08-07", "unauthorized_return_window": "2023-10-07", "expected_settlement_date": "2023-08-04", "originator_client_id": "569ed2f36b3a3a021713abc1", "recurring_transfer_id": null, "credit_funds_source": "sweep", "facilitator_fee": "1.23", "network_trace_id": null }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/cancel  #### Cancel a transfer  Use the [/transfer/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercancel) endpoint to cancel a transfer. A transfer is eligible for cancellation if the `cancellable` property returned by [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) is `true`. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a transfer. string Specifies the reason for cancelling transfer. This is required for RfP transfers, and will be ignored for other networks. `"AC03"` - Invalid Creditor Account Number `"AM09"` - Incorrect Amount `"CUST"` - Requested By Customer - Cancellation requested `"DUPL"` - Duplicate Payment `"FRAD"` - Fraudulent Payment - Unauthorized or fraudulently induced `"TECH"` - Technical Problem - Cancellation due to system issues `"UPAY"` - Undue Payment - Payment was made through another channel `"AC14"` - Invalid or Missing Creditor Account Type `"AM06"` - Amount Too Low `"BE05"` - Unrecognized Initiating Party `"FOCR"` - Following Refund Request `"MS02"` - No Specified Reason - Customer `"MS03"` - No Specified Reason - Agent `"RR04"` - Regulatory Reason `"RUTA"` - Return Upon Unable To Apply Possible values: `AC03`, `AM09`, `CUST`, `DUPL`, `FRAD`, `TECH`, `UPAY`, `AC14`, `AM06`, `BE05`, `FOCR`, `MS02`, `MS03`, `RR04`, `RUTA` ```bash curl -X POST https://sandbox.plaid.com/transfer/cancel \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "transfer_id": "123004561178933" }' ``` ```python request = TransferCancelRequest(transfer_id='123004561178933') response = client.transfer_cancel(request) ``` ```node const request: TransferCancelRequest = { transfer_id: '123004561178933', }; try { const response = await plaidClient.transferCancel(request); const request_id = response.data.request_id; } catch (error) { // handle error } ``` ```java TransferCancelRequest request = new TransferCancelRequest() .transferId("123004561178933"); Response response = client() .transferCancel(request) .execute(); ``` ```ruby request = Plaid::TransferCancelRequest.new({ transfer_id: '123004561178933' }) response = client.transfer_cancel(request) ``` ```go request := plaid.NewTransferCancelRequest( "123004561178933" ) response, _, err := client.PlaidApi.TransferCancel(ctx).TransferCancelRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "saKrIBuEB9qJZno" } ``` --- # API - Plaid Ledger | Plaid Docs Plaid Ledger  ============= #### API reference for Plaid Ledger  For how-to guidance, see the [Ledger documentation](https://plaid.com/docs/transfer/flow-of-funds/index.html.md) . | Plaid Ledger | | | --- | --- | | [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) | Deposit funds into a ledger balance held with Plaid | | [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) | Move available balance between platform and its originator | | [/transfer/ledger/get](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerget) | Retrieve information about the ledger balance held with Plaid | | [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) | Withdraw funds from a ledger balance held with Plaid | | [/transfer/ledger/event/list](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgereventlist) | Retrieve a list of ledger balance events | \=\*=\*=\*= #### /transfer/ledger/deposit  #### Deposit funds into a Plaid Ledger balance  Use the [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) endpoint to deposit funds into Plaid Ledger. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Client ID of the customer that owns the Ledger balance. This is so Plaid knows which of your customers to payout or collect funds. Only applicable for [Platform customers](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) . Do not include if you’re paying out to yourself. string Specify which funding account to use. Customers can find a list of `funding_account_id`s in the Accounts page of the Plaid Dashboard, under the "Account ID" column. If this field is left blank, the funding account associated with the specified Ledger will be used. If an `originator_client_id` is specified, the `funding_account_id` must belong to the specified originator. string Specify which ledger balance to deposit to. Customers can find a list of `ledger_id`s in the Accounts page of your Plaid Dashboard. If this field is left blank, this will default to id of the default ledger balance. required, string A positive amount of how much will be deposited into ledger (decimal string with two digits of precision e.g. "5.50"). string The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement. Max length: `10` required, string A unique key provided by the client, per unique ledger deposit. Maximum of 50 characters. The API supports idempotency for safely retrying the request without accidentally performing the same operation twice. For example, if a request to create a ledger deposit fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single deposit is created. Max length: `50` required, string The ACH networks used for the funds flow. For requests submitted as either `ach` or `same-day-ach` the cutoff for Same Day ACH is 3:00 PM Eastern Time and the cutoff for Standard ACH transfers is 8:30 PM Eastern Time. It is recommended to submit a request at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any request that is indicated as `same-day-ach` and that misses the Same Day ACH cutoff, but is submitted in time for the Standard ACH cutoff, will be sent over Standard ACH rails and will not incur same-day charges. Possible values: `ach`, `same-day-ach` ```node const request: TransferLedgerDepositRequest = { amount: '12.34', network: 'ach', idempotency_key: 'test_deposit_abc', description: 'deposit', }; try { const response = await client.transferLedgerDeposit(request); const sweep = response.data.sweep; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/ledger/deposit \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "amount": "12.34", "network": "ach", "idempotency_key": "test_deposit_abc", "description": "deposit", }' ``` ```ruby request = Plaid::TransferLedgerDepositRequest.new( { amount: "12.34", network: "ach", idempotency_key: "test_deposit_abc", description: "deposit", } ) response = client.transfer_ledger_deposit(request) sweep = response.sweep ``` ```java TransferLedgerDepositRequest request = new TransferLedgerDepositRequest() .amount("12.34") .network("ach") .idempotencyKey("test_deposit_abc") .description("deposit"); Response response = client() .transferLedgerDeposit(request) .execute(); Sweep sweep = response.body().getSweep(); ``` ```python request = TransferLedgerDepositRequest( amount='12.34', network='ach', idempotency_key='test_deposit_abc', description='deposit', ) response = client.transfer_ledger_deposit(request) sweep = response['sweep'] ``` ```go request := plaid.NewTransferLedgerDepositRequest( "12.34", "test_deposit_abc", "ach" ) response, _, err := client.PlaidApi.TransferLedgerDeposit(ctx).TransferLedgerDepositRequest(*request).Execute() ``` #### Response fields  object Describes a sweep of funds to / from the sweep account. A sweep is associated with many sweep events (events of type `swept` or `return_swept`) which can be retrieved by invoking the `/transfer/event/list` endpoint with the corresponding `sweep_id`. `swept` events occur when the transfer amount is credited or debited from your sweep account, depending on the `type` of the transfer. `return_swept` events occur when a transfer is returned and Plaid undoes the credit or debit. The total sum of the `swept` and `return_swept` events is equal to the `amount` of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger. string Identifier of the sweep. string The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The datetime when the sweep occurred, in RFC 3339 format. Format: `date-time` string Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00") If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced. string The currency of the sweep, e.g. "USD". nullable, string The date when the sweep settled, in the YYYY-MM-DD format. Format: `date` nullable, string The expected date when funds from a ledger deposit will be made available and can be withdrawn from the associated ledger balance. Only applies to deposits. This will be of the form YYYY-MM-DD. Format: `date` nullable, string The status of a sweep transfer `"pending"` - The sweep is currently pending `"posted"` - The sweep has been posted `"settled"` - The sweep has settled. This is the terminal state of a successful credit sweep. `"returned"` - The sweep has been returned. This is the terminal state of a returned sweep. Returns of a sweep are extremely rare, since sweeps are money movement between your own bank account and your own Ledger. `"funds_available"` - Funds from the sweep have been released from hold and applied to the ledger's available balance. (Only applicable to deposits.) This is the terminal state of a successful deposit sweep. `"failed"` - The sweep has failed. This is the terminal state of a failed sweep. Possible values: `pending`, `posted`, `settled`, `funds_available`, `returned`, `failed`, `null` nullable, string The trigger of the sweep `"manual"` - The sweep is created manually by the customer `"incoming"` - The sweep is created by incoming funds flow (e.g. Incoming Wire) `"balance_threshold"` - The sweep is created by balance threshold setting `"automatic_aggregate"` - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance. Possible values: `manual`, `incoming`, `balance_threshold`, `automatic_aggregate` string The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement. nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. nullable, object The failure reason if the status for a sweep is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the sweep status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. nullable, string A human-readable description of the reason for the failure or reversal. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "sweep": { "id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "created": "2020-08-06T17:27:15Z", "amount": "-12.34", "iso_currency_code": "USD", "settled": null, "status": "pending", "trigger": "manual", "description": "deposit", "network_trace_id": null }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/ledger/distribute  #### Move available balance between ledgers  Use the [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) endpoint to move available balance between ledgers, if you have multiple. If you’re a platform, you can move funds between one of your ledgers and one of your customer’s ledger. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The Ledger to pull money from. required, string The Ledger to credit money to. required, string The amount to move (decimal string with two digits of precision e.g. "10.00"). Amount must be positive. required, string A unique key provided by the client, per unique ledger distribute. Maximum of 50 characters. The API supports idempotency for safely retrying the request without accidentally performing the same operation twice. For example, if a request to create a ledger distribute fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single distribute is created. Max length: `50` string An optional description for the ledger distribute operation. ```node const request: TransferLedgerDistributeRequest = { from_client_id: '6a65dh3d1h0d1027121ak184', to_client_id: '415ab64b87ec47401d000002', amount: '12.34', idempotency_key: 'test_distribute_abc', description: 'distribute', }; try { const response = await client.transferLedgerDistribute(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/ledger/distribute \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "amount": "12.34", "from_client_id": "6a65dh3d1h0d1027121ak184", "to_client_id": "415ab64b87ec47401d000002", "idempotency_key": "test_distribute_abc", "description": "distribute", }' ``` ```ruby request = Plaid::TransferLedgerDistributeRequest.new( { amount: "12.34", from_client_id: "6a65dh3d1h0d1027121ak184", to_client_id: "415ab64b87ec47401d000002", idempotency_key: "test_distribute_abc", description: "distribute", } ) response = client.transfer_ledger_distribute(request) ``` ```java TransferLedgerDistributeRequest request = new TransferLedgerDistributeRequest() .fromClientId("6a65dh3d1h0d1027121ak184") .toClientId("415ab64b87ec47401d000002") .amount("12.34") .idempotencyKey("test_distribute_abc") .description("distribute"); Response response = client() .transferLedgerDistribute(request) .execute(); ``` ```python request = TransferLedgerDistributeRequest( amount='12.34', from_client_id="6a65dh3d1h0d1027121ak184", to_client_id="415ab64b87ec47401d000002", idempotency_key='test_distribute_abc', description='distribute', ) response = client.transfer_ledger_distribute(request) ``` ```go request := plaid.NewTransferLedgerDistributeRequest( "6a65dh3d1h0d1027121ak184", "415ab64b87ec47401d000002", "12.34", "test_distribute_abc", "distribute" ) response, _, err := client.PlaidApi.TransferLedgerDistribute(ctx).TransferLedgerDistributeRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/ledger/get  #### Retrieve Plaid Ledger balance  Use the [/transfer/ledger/get](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerget) endpoint to view a balance on the ledger held with Plaid. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Specify which ledger balance to get. Customers can find a list of `ledger_id`s in the Accounts page of your Plaid Dashboard. If this field is left blank, this will default to id of the default ledger balance. string Client ID of the end customer. ```node try { const response = await client.transferLedgerGet({}); const available_balance = response.data.balance.available; const pending_balance = response.data.balance.pending; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/ledger/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}" }' ``` ```ruby response = client.transfer_ledger_get({}) available_balance = response.balance.available ``` ```java Response response = client().transferLedgerGet(new Object()).execute(); String availableBalance = response.body().getBalance().getAvailable(); ``` ```python response = client.transfer_ledger_get({}) available_balance = response['balance']['available'] ``` ```go resp, _, err := client.PlaidApi.TransferLedgerGet(ctx).Body(nil).Execute() if err != nil { plaidErr, _ := plaid.ToPlaidError(err) fmt.Println(plaidErr.ErrorMessage) } balance, ok := resp.GetBalance().GetAvailable(); ``` #### Response fields  string The unique identifier of the Ledger that was returned. object Information about the balance of the ledger held with Plaid. string The amount of this balance available for use (decimal string with two digits of precision e.g. "10.00"). string The amount of pending funds that are in processing (decimal string with two digits of precision e.g. "10.00"). string The name of the Ledger boolean Whether this Ledger is the client's default ledger. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "name": "Default", "is_default": true, "balance": { "available": "1721.70", "pending": "123.45" }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/ledger/withdraw  #### Withdraw funds from a Plaid Ledger balance  Use the [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) endpoint to withdraw funds from a Plaid Ledger balance. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Client ID of the customer that owns the Ledger balance. This is so Plaid knows which of your customers to payout or collect funds. Only applicable for [Platform customers](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) . Do not include if you’re paying out to yourself. string Specify which funding account to use. Customers can find a list of `funding_account_id`s in the Accounts page of the Plaid Dashboard, under the "Account ID" column. If this field is left blank, the funding account associated with the specified Ledger will be used. If an `originator_client_id` is specified, the `funding_account_id` must belong to the specified originator. string Specify which ledger balance to withdraw from. Customers can find a list of `ledger_id`s in the Accounts page of your Plaid Dashboard. If this field is left blank, this will default to id of the default ledger balance. required, string A positive amount of how much will be withdrawn from the ledger balance (decimal string with two digits of precision e.g. "5.50"). string The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement. Max length: `10` required, string A unique key provided by the client, per unique ledger withdraw. Maximum of 50 characters. The API supports idempotency for safely retrying the request without accidentally performing the same operation twice. For example, if a request to create a ledger withdraw fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single withdraw is created. Max length: `50` required, string The network or rails used for the transfer. For transfers submitted as `ach` or `same-day-ach`, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted as `same-day-ach`, the Same Day ACH cutoff is 3:00 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail. For transfers submitted as `rtp`, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as `rtp` and the counterparty account is not eligible for RTP, the `/transfer/authorization/create` request will fail with an `INVALID_FIELD` error code. To pre-check to determine whether a counterparty account can support RTP, call `/transfer/capabilities/get` before calling `/transfer/authorization/create`. Wire transfers are currently in early availability. To request access to `wire` as a payment network, contact your Account Manager. For transfers submitted as `wire`, the `type` must be `credit`; wire debits are not supported. The cutoff to submit a wire payment is 6:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail. Possible values: `ach`, `same-day-ach`, `rtp`, `wire` ```node const request: TransferLedgerWithdrawRequest = { amount: '12.34', network: 'ach', idempotency_key: 'test_deposit_abc', description: 'withdraw', }; try { const response = await client.transferLedgerWithdraw(request); const sweep = response.data.sweep; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/ledger/withdraw \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "amount": "12.34", "network": "ach", "idempotency_key": "test_withdraw_abc", "description": "withdraw", }' ``` ```ruby request = Plaid::TransferLedgerWithdrawRequest.new( { amount: "12.34", network: "ach", idempotency_key: "test_withdraw_abc", description: "withdraw", } ) response = client.transfer_ledger_withdraw(request) sweep = response.sweep ``` ```java TransferLedgerWithdrawRequest request = new TransferLedgerWithdrawRequest() .amount("12.34") .network("ach") .idempotencyKey("test_withdraw_abc") .description("withdraw"); Response response = client() .transferLedgerWithdraw(request) .execute(); Sweep sweep = response.body().getSweep(); ``` ```python request = TransferLedgerWithdrawRequest( amount='12.34', network='ach', idempotency_key='test_withdraw_abc', description='withdraw', ) response = client.transfer_ledger_withdraw(request) sweep = response['sweep'] ``` ```go request := plaid.NewTransferLedgerWithdrawRequest( "12.34", "test_withdraw_abc", "ach", ) response, _, err := client.PlaidApi.TransferLedgerWithdraw(ctx).TransferLedgerWithdrawRequest(*request).Execute() ``` #### Response fields  object Describes a sweep of funds to / from the sweep account. A sweep is associated with many sweep events (events of type `swept` or `return_swept`) which can be retrieved by invoking the `/transfer/event/list` endpoint with the corresponding `sweep_id`. `swept` events occur when the transfer amount is credited or debited from your sweep account, depending on the `type` of the transfer. `return_swept` events occur when a transfer is returned and Plaid undoes the credit or debit. The total sum of the `swept` and `return_swept` events is equal to the `amount` of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger. string Identifier of the sweep. string The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The datetime when the sweep occurred, in RFC 3339 format. Format: `date-time` string Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00") If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced. string The currency of the sweep, e.g. "USD". nullable, string The date when the sweep settled, in the YYYY-MM-DD format. Format: `date` nullable, string The expected date when funds from a ledger deposit will be made available and can be withdrawn from the associated ledger balance. Only applies to deposits. This will be of the form YYYY-MM-DD. Format: `date` nullable, string The status of a sweep transfer `"pending"` - The sweep is currently pending `"posted"` - The sweep has been posted `"settled"` - The sweep has settled. This is the terminal state of a successful credit sweep. `"returned"` - The sweep has been returned. This is the terminal state of a returned sweep. Returns of a sweep are extremely rare, since sweeps are money movement between your own bank account and your own Ledger. `"funds_available"` - Funds from the sweep have been released from hold and applied to the ledger's available balance. (Only applicable to deposits.) This is the terminal state of a successful deposit sweep. `"failed"` - The sweep has failed. This is the terminal state of a failed sweep. Possible values: `pending`, `posted`, `settled`, `funds_available`, `returned`, `failed`, `null` nullable, string The trigger of the sweep `"manual"` - The sweep is created manually by the customer `"incoming"` - The sweep is created by incoming funds flow (e.g. Incoming Wire) `"balance_threshold"` - The sweep is created by balance threshold setting `"automatic_aggregate"` - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance. Possible values: `manual`, `incoming`, `balance_threshold`, `automatic_aggregate` string The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement. nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. nullable, object The failure reason if the status for a sweep is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the sweep status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. nullable, string A human-readable description of the reason for the failure or reversal. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "sweep": { "id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "created": "2020-08-06T17:27:15Z", "amount": "12.34", "iso_currency_code": "USD", "settled": null, "status": "pending", "trigger": "manual", "description": "withdraw", "network_trace_id": null }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/ledger/event/list  #### List transfer ledger events  Use the [/transfer/ledger/event/list](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgereventlist) endpoint to get a list of ledger events for a specific ledger based on specified filter criteria. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Filter transfer events to only those with the specified originator client. (This field is specifically for resellers. Caller's client ID will be used if this field is not specified.) string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The start created datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: `date-time` string The end created datetime of transfers to list. This should be in RFC 3339 format (i.e. 2019-12-06T22:35:49Z) Format: `date-time` string Plaid's unique identifier for a Plaid Ledger Balance. string Plaid's unique identifier for the ledger event. string Source of the ledger event. `"TRANSFER"` - The source of the ledger event is a transfer `"SWEEP"` - The source of the ledger event is a sweep `"REFUND"` - The source of the ledger event is a refund Possible values: `TRANSFER`, `SWEEP`, `REFUND` string Plaid's unique identifier for a transfer, sweep, or refund. integer The maximum number of transfer events to return. If the number of events matching the above parameters is greater than `count`, the most recent events will be returned. Default: `25` Maximum: `25` Minimum: `1` integer The offset into the list of transfer events. When `count`\=25 and `offset`\=0, the first 25 events will be returned. When `count`\=25 and `offset`\=25, the next 25 events will be returned. Default: `0` Minimum: `0` ```node const request: TransferLedgerEventListRequest = { originator_client_id: "8945fedc-e703-463d-86b1-dc0607b55460", start_date: '2019-12-06T22:35:49Z', end_date: '2019-12-12T22:35:49Z', count: 14, offset: 2, ledger_id: "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", ledger_event_id: "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", source_type: "transfer", source_id: "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", }; try { const response = await plaidClient.transferLedgerEventList(request); const events = response.data.ledger_events; for (const event of events) { // iterate through events } } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/ledger/event/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "originator_client_id": "8945fedc-e703-463d-86b1-dc0607b55460", "start_date": "2019-12-06T22:35:49Z", "end_date": "2019-12-12T22:35:49Z", "count": 14, "offset": 0, "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "ledger_event_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "source_type": "transfer", "source_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9" }' ``` ```ruby require 'time' request = Plaid::TransferLedgerEventListRequest.new( { originator_client_id: '8945fedc-e703-463d-86b1-dc0607b55460', start_date: Time.parse('2019-12-06T22:35:49Z'), end_date: Time.parse('2019-12-12T22:35:49Z'), count: 14, offset: 2, ledger_id: '563db5f8-4c95-4e17-8c3e-cb988fb9cf1a', ledger_event_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', source_type: 'transfer', source_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', } ) response = client.transfer_ledger_event_list(request) response.ledger_events.each do |event| # iterate through events end ``` ```java import java.time.OffsetDateTime; import java.util.ArrayList; import java.util.List; OffsetDateTime startDate = OffsetDateTime.parse("2019-12-06T22:35:49+00:00"); OffsetDateTime endDate = OffsetDateTime.parse("2019-12-12T22:35:49+00:00"); TransferLedgerEventListRequest request = new TransferLedgerEventListRequest() .originatorClientId("8945fedc-e703-463d-86b1-dc0607b55460") .startDate(startDate) .endDate(endDate) .count(14) .offset(2) .ledgerId("563db5f8-4c95-4e17-8c3e-cb988fb9cf1a") .ledgerEventId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr") .sourceType("transfer") .sourceId("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9"); Response response = client() .transferLedgerEventList(request) .execute(); List ledgerEvents = response.body().getLedgerEvents(); for (TransferLedgerEvent e : ledgerEvents) { // iterate through events } ``` ```python import datetime request = TransferLedgerEventListRequest( originator_client_id='8945fedc-e703-463d-86b1-dc0607b55460', start_date=datetime.datetime(2019, 12, 6, 22, 35, 49, tzinfo=datetime.timezone.utc), end_date=datetime.datetime(2019, 12, 12, 22, 35, 49, tzinfo=datetime.timezone.utc), count=14, offset=2, ledger_id='563db5f8-4c95-4e17-8c3e-cb988fb9cf1a', ledger_event_id='3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', source_type='transfer', source_id='460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9' ) response = client.transfer_ledger_event_list(request) events = response['ledger_events'] for event in events: # iterate through events ``` ```go request := plaid.NewTransferLedgerEventListRequest() request.SetOriginatorClientId("8945fedc-e703-463d-86b1-dc0607b55460") request.SetStartDate(time.Date(2019, time.December, 6, 22, 35, 49, 0, time.UTC)) request.SetEndDate(time.Date(2019, time.December, 12, 22, 35, 49, 0, time.UTC)) request.SetCount(14) request.SetOffset(2) request.SetLedgerId("563db5f8-4c95-4e17-8c3e-cb988fb9cf1a") request.SetLedgerEventId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr") request.SetSourceType("transfer") request.SetSourceId("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9") response, _, err := client.PlaidApi.TransferLedgerEventList(ctx).TransferLedgerEventListRequest(*request).Execute() ``` #### Response fields  \[object\] string Plaid's unique identifier for this ledger event. string The ID of the ledger this event belongs to. string The amount of the ledger event as a decimal string. nullable, string The ID of the transfer source that triggered this ledger event. nullable, string The ID of the refund source that triggered this ledger event. nullable, string The ID of the sweep source that triggered this ledger event. string A description of the ledger event. string The new pending balance after this event. string The new available balance after this event. string The type of balance that was impacted by this event. string The datetime when this ledger event occurred. Format: `date-time` boolean Whether there are more events to be pulled from the endpoint that have not already been returned string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "ledger_events": [ { "ledger_event_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "amount": "100.00", "type": "deposit", "transfer_id": "460cbe92-2dcc-8eae", "description": "Converted to available", "pending_balance": "100.00", "available_balance": "100.00", "timestamp": "2023-12-01T10:00:00Z" } ], "has_more": false, "request_id": "mdqfuVxeoza6mhu" } ``` --- # API - Program Metrics | Plaid Docs Program Metrics  ================ #### API reference for Transfer program metrics  For how-to guidance, see the [Transfer documentation](https://plaid.com/docs/transfer/index.html.md) . | Program Metrics | | | --- | --- | | [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) | Get transfer product usage metrics | | [/transfer/configuration/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transferconfigurationget) | Get transfer product configuration | \=\*=\*=\*= #### /transfer/metrics/get  #### Get transfer product usage metrics  Use the [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) endpoint to view your transfer product usage metrics. In the Sandbox environment, this endpoint returns static placeholder values rather than metrics computed from your Sandbox transfer activity. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The Plaid client ID of the transfer originator. Should only be present if `client_id` is a [Platform customer](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) . ```node const request: TransferMetricsGetRequest = { originator_client_id: '61b8f48ded273e001aa8db6d', }; try { const response = await client.transferMetricsGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/metrics/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "originator_client_id": "61b8f48ded273e001aa8db6d" }' ``` ```ruby request = Plaid::TransferMetricsGetRequest.new( { originator_client_id: "61b8f48ded273e001aa8db6d", } ) response = client.transfer_metrics_get(request) ``` ```java TransferMetricsGetRequest request = new TransferMetricsGetRequest() .originatorClientId("61b8f48ded273e001aa8db6d"); Response response = client() .transferMetricsGet(request) .execute(); ``` ```python request = TransferMetricsGetRequest( originator_client_id='61b8f48ded273e001aa8db6d', ) response = client.transfer_metrics_get(request) ``` ```go request := plaid.NewTransferMetricsGetRequest(); request.SetOriginatorClientId("61b8f48ded273e001aa8db6d"); response, _, err := client.PlaidApi.TransferMetricsGet(ctx).TransferMetricsGetRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. string Sum of dollar amount of debit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00"). string Sum of dollar amount of credit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00"). string Sum of dollar amount of debit transfers in current calendar month (decimal string with two digits of precision e.g. "10.00"). string Sum of dollar amount of credit transfers in current calendar month (decimal string with two digits of precision e.g. "10.00"). string The currency of the dollar amount, e.g. "USD". nullable, object Details regarding return rates. nullable, object Details regarding return rates. string The overall return rate. string The unauthorized return rate. string The administrative return rate. nullable, object Details regarding authorization usage. string The daily credit utilization formatted as a decimal. string The daily debit utilization formatted as a decimal. string The monthly credit utilization formatted as a decimal. string The monthly debit utilization formatted as a decimal. Response Object ```json { "daily_debit_transfer_volume": "1234.56", "daily_credit_transfer_volume": "567.89", "monthly_transfer_volume": "", "monthly_debit_transfer_volume": "10000.00", "monthly_credit_transfer_volume": "2345.67", "iso_currency_code": "USD", "request_id": "saKrIBuEB9qJZno", "return_rates": { "last_60d": { "overall_return_rate": "0.1023", "administrative_return_rate": "0.0160", "unauthorized_return_rate": "0.0028" } }, "authorization_usage": { "daily_credit_utilization": "0.2300", "daily_debit_utilization": "0.3401", "monthly_credit_utilization": "0.9843", "monthly_debit_utilization": "0.3220" } } ``` \=\*=\*=\*= #### /transfer/configuration/get  #### Get transfer product configuration  Use the [/transfer/configuration/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transferconfigurationget) endpoint to view your transfer product configurations. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The Plaid client ID of the transfer originator. Should only be present if `client_id` is a [Platform customer](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) . ```node const request: TransferConfigurationGetRequest = { originator_client_id: '61b8f48ded273e001aa8db6d', }; try { const response = await client.transferConfigurationGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/configuration/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "originator_client_id": "61b8f48ded273e001aa8db6d" }' ``` ```ruby request = Plaid::TransferConfigurationGetRequest.new( { originator_client_id: "61b8f48ded273e001aa8db6d", } ) response = client.transfer_configuration_get(request) ``` ```java TransferConfigurationGetRequest request = new TransferConfigurationGetRequest() .originatorClientId("61b8f48ded273e001aa8db6d"); Response response = client() .transferConfigurationGet(request) .execute(); ``` ```python request = TransferConfigurationGetRequest( originator_client_id='61b8f48ded273e001aa8db6d', ) response = client.transfer_configuration_get(request) ``` ```go request := plaid.NewTransferConfigurationGetRequest(); request.SetOriginatorClientId("61b8f48ded273e001aa8db6d"); response, _, err := client.PlaidApi.TransferConfigurationGet(ctx).TransferConfigurationGetRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. string The max limit of dollar amount of a single credit transfer (decimal string with two digits of precision e.g. "10.00"). string The max limit of dollar amount of a single debit transfer (decimal string with two digits of precision e.g. "10.00"). string The max limit of sum of dollar amount of credit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00"). string The max limit of sum of dollar amount of debit transfers in last 24 hours (decimal string with two digits of precision e.g. "10.00"). string The max limit of sum of dollar amount of credit transfers in one calendar month (decimal string with two digits of precision e.g. "10.00"). string The max limit of sum of dollar amount of debit transfers in one calendar month (decimal string with two digits of precision e.g. "10.00"). string The currency of the dollar amount, e.g. "USD". Response Object ```json { "max_single_transfer_amount": "", "max_single_transfer_credit_amount": "1000.00", "max_single_transfer_debit_amount": "1000.00", "max_daily_credit_amount": "50000.00", "max_daily_debit_amount": "50000.00", "max_monthly_amount": "", "max_monthly_credit_amount": "500000.00", "max_monthly_debit_amount": "500000.00", "iso_currency_code": "USD", "request_id": "saKrIBuEB9qJZno" } ``` --- # API - Transfer for Platforms | Plaid Docs Transfer for Platforms  ======================= #### API reference for Transfer for Platforms endpoints  For how-to guidance, see the [Transfer for Platforms documentation](https://plaid.com/docs/transfer/platform-payments/index.html.md) . | Transfer for Platforms | | | --- | --- | | [/transfer/platform/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformoriginatorcreate) | Pass transfer specific onboarding info for the originator | | [/transfer/platform/person/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformpersoncreate) | Create each individual who is a beneficial owner or control person of the business | | [/transfer/platform/requirement/submit](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformrequirementsubmit) | Pass additional data Plaid needs to make an onboarding decision for the originator | | [/transfer/platform/document/submit](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformdocumentsubmit) | Submit documents Plaid needs to verify information about the originator | | [/transfer/originator/get](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorget) | Get the status of an originator's onboarding | | [/transfer/originator/list](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorlist) | Get the status of all originators' onboarding | | [/transfer/originator/funding\_account/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorfunding_accountcreate) | Create a new funding account for an originator | \=\*=\*=\*= #### /transfer/platform/originator/create  #### Create an originator for Transfer for Platforms customers  Use the [/transfer/platform/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformoriginatorcreate) endpoint to submit information about the originator you are onboarding, including the originator's agreement to the required legal terms. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The client ID of the originator required, object Metadata related to the acceptance of Terms of Service required, boolean Indicates whether the TOS agreement was accepted required, string The IP address of the originator when they accepted the TOS. Formatted as an IPv4 or IPv6 IP address required, string ISO8601 timestamp indicating when the originator accepted the TOS Format: `date-time` required, string ISO8601 timestamp indicating the most recent time the platform collected onboarding data from the originator Format: `date-time` string The webhook URL to which a `PLATFORM_ONBOARDING_UPDATE` webhook should be sent. Format: `url` ```node const request: TransferPlatformOriginatorCreateRequest = { originator_client_id: "6a65dh3d1h0d1027121ak184", tos_acceptance_metadata: { agreement_accepted: true, originator_ip_address: "192.0.2.42", agreement_accepted_at: "2017-09-14T14:42:19.350Z" }, originator_reviewed_at: "2024-07-29T20:22:21Z", webhook: "https://webhook.com/webhook" }; try { const response = await client.transferPlatformOriginatorCreate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/platform/originator/create \ -H 'Content-Type: application/json' \ -d '{ "originator_client_id": "6a65dh3d1h0d1027121ak184", "tos_acceptance_metadata": { "agreement_accepted": true, "originator_ip_address": "192.0.2.42", "agreement_accepted_at": "2017-09-14T14:42:19.350Z" }, "originator_reviewed_at": "2024-07-29T20:22:21Z", "webhook": "https://webhook.com/webhook" }' ``` ```ruby request = Plaid::TransferPlatformOriginatorCreateRequest.new( { originator_client_id: "6a65dh3d1h0d1027121ak184", tos_acceptance_metadata: { agreement_accepted: true, originator_ip_address: "192.0.2.42", agreement_accepted_at: "2017-09-14T14:42:19.350Z" }, originator_reviewed_at: "2024-07-29T20:22:21Z", webhook: "https://webhook.com/webhook" } ) response = client.transfer_platform_originator_create(request) ``` ```java TransferPlatformTOSAcceptanceMetadata tosMetadata = new TransferPlatformTOSAcceptanceMetadata() .agreementAccepted(true) .originatorIpAddress("192.0.2.42") .agreementAcceptedAt(OffsetDateTime.parse("2017-09-14T14:42:19.350Z")); TransferPlatformOriginatorCreateRequest request = new TransferPlatformOriginatorCreateRequest() .originatorClientId("6a65dh3d1h0d1027121ak184") .tosAcceptanceMetadata(tosMetadata) .originatorReviewedAt(OffsetDateTime.parse("2024-07-29T20:22:21Z")) .webhook("https://webhook.com/webhook"); Response response = client() .transferPlatformOriginatorCreate(request) .execute(); TransferPlatformOriginatorCreateResponse originator = response.body(); ``` ```python request = TransferPlatformOriginatorCreateRequest( originator_client_id="6a65dh3d1h0d1027121ak184", tos_acceptance_metadata={ "agreement_accepted": True, "originator_ip_address": "192.0.2.42", "agreement_accepted_at": "2017-09-14T14:42:19.350Z" }, originator_reviewed_at="2024-07-29T20:22:21Z", webhook="https://webhook.com/webhook" ) response = client.transfer_platform_originator_create(request) ``` ```go request := plaid.NewTransferPlatformOriginatorCreateRequest( "6a65dh3d1h0d1027121ak184", ) tosMetadata := plaid.TransferPlatformTosAcceptanceMetadata{ AgreementAccepted: plaid.PtrBool(true), OriginatorIpAddress: plaid.PtrString("192.0.2.42"), AgreementAcceptedAt: plaid.PtrTime(time.Date(2017, 9, 14, 14, 42, 19, 350000000, time.UTC)), } request.SetTosAcceptanceMetadata(tosMetadata) request.SetOriginatorReviewedAt(time.Date(2024, 7, 29, 20, 22, 21, 0, time.UTC)) request.SetWebhook("https://webhook.com/webhook") response, _, err := client.PlaidApi.TransferPlatformOriginatorCreate(ctx). TransferPlatformOriginatorCreateRequest(*request). Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/platform/person/create  #### Create a person associated with an originator  Use the [/transfer/platform/person/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformpersoncreate) endpoint to create a person associated with an originator (e.g. beneficial owner or control person) and optionally submit personal identification information for them. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The client ID of the originator object The person's legal name required, string A string with at least one non-whitespace character, with a max length of 100 characters. required, string A string with at least one non-whitespace character, with a max length of 100 characters. string A valid email address. Must not have leading or trailing spaces. string A valid phone number in E.164 format. Phone number input may be validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. object Home address of a person required, string The full city name. required, string Valid, capitalized, two-letter ISO code representing the country of this object. Must be in ISO 3166-1 alpha-2 form. required, string The postal code of the address. required, string An ISO 3166-2 subdivision code. Related terms would be "state", "province", "prefecture", "zone", "subdivision", etc. required, string The primary street portion of an address. A string with at least one non-whitespace alphabetical character, with a max length of 80 characters. string Extra street information, like an apartment or suite number. If provided, a string with at least one non-whitespace character, with a max length of 50 characters. object ID number of the person required, string Value of the person's ID Number. Alpha-numeric, with all formatting characters stripped. required, string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` string The date of birth of the person. Formatted as YYYY-MM-DD. Format: `date` string The relationship between this person and the originator they are related to. integer The percentage of ownership this person has in the onboarding business. Only applicable to beneficial owners with 25% or more ownership. Minimum: `25` Maximum: `100` string The title of the person at the business. Only applicable to control persons - for example, "CEO", "President", "Owner", etc. ```node const request: TransferPlatformPersonCreateRequest = { originator_client_id: "6a65dh3d1h0d1027121ak184", name: { given_name: "Owen", family_name: "Gillespie" }, email_address: "ogillespie@plaid.com", phone_number: "+12223334444", address: { street: "123 Main St.", street2: "Apt 456", city: "San Francisco", region: "CA", postal_code: "94580", country: "US" }, id_number: { type: "us_ssn", value: "111223333" }, date_of_birth: "2000-01-20", relationship_to_originator: "BENEFICIAL_OWNER", ownership_percentage: 50, title: "COO" }; try { const response = await client.transferPlatformPersonCreate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/platform/person/create \ -H 'Content-Type: application/json' \ -d '{ "originator_client_id": , "name": { "given_name": "Owen", "family_name": "Gillespie" }, "email_address": "ogillespie@plaid.com", "phone_number": "+12223334444", "address": { "street": "123 Main St.", "street2": "Apt 456", "city": "San Francisco", "region": "CA", "postal_code": "94580", "country": "US" }, "id_number": { "type": "us_ssn", "value": "111223333" }, "date_of_birth": "2000-01-20", "relationship_to_originator": "BENEFICIAL_OWNER", "ownership_percentage": 50, "title": "COO" }' ``` ```ruby request = Plaid::TransferPlatformPersonCreateRequest.new( { originator_client_id: "6a65dh3d1h0d1027121ak184", name: { given_name: "Owen", family_name: "Gillespie" }, email_address: "ogillespie@plaid.com", phone_number: "+12223334444", address: { street: "123 Main St.", street2: "Apt 456", city: "San Francisco", region: "CA", postal_code: "94580", country: "US" }, id_number: { type: "us_ssn", value: "111223333" }, date_of_birth: "2000-01-20", relationship_to_originator: "BENEFICIAL_OWNER", ownership_percentage: 50, title: "COO" } ) response = client.transfer_platform_person_create(request) ``` ```java TransferPlatformPersonCreateRequest request = new TransferPlatformPersonCreateRequest() .originatorClientId("6a65dh3d1h0d1027121ak184") .name(new TransferPlatformPersonName() .givenName("Owen") .familyName("Gillespie") ) .emailAddress("ogillespie@plaid.com") .phoneNumber("+12223334444") .address(new TransferPlatformAddress() .street("123 Main St.") .street2("Apt 456") .city("San Francisco") .region("CA") .postalCode("94580") .country("US") ) .idNumber(new TransferPlatformIdNumber() .type("us_ssn") .value("111223333") ) .dateOfBirth(LocalDate.parse("2000-01-20")) .relationshipToOriginator("BENEFICIAL_OWNER") .ownershipPercentage(50) .title("COO"); Response response = client() .transferPlatformPersonCreate(request) .execute(); TransferPlatformPersonCreateResponse person = response.body(); ``` ```python request = TransferPlatformPersonCreateRequest( originator_client_id="6a65dh3d1h0d1027121ak184", name={ "given_name": "Owen", "family_name": "Gillespie" }, email_address="ogillespie@plaid.com", phone_number="+12223334444", address={ "street": "123 Main St.", "street2": "Apt 456", "city": "San Francisco", "region": "CA", "postal_code": "94580", "country": "US" }, id_number={ "type": "us_ssn", "value": "111223333" }, date_of_birth="2000-01-20", relationship_to_originator="BENEFICIAL_OWNER", ownership_percentage=50, title="COO" ) response = client.transfer_platform_person_create(request) ``` ```go request := plaid.NewTransferPlatformPersonCreateRequest( "6a65dh3d1h0d1027121ak184", ) name := plaid.TransferPlatformPersonName{ GivenName: plaid.PtrString("Owen"), FamilyName: plaid.PtrString("Gillespie"), } address := plaid.TransferPlatformPersonAddress{ Street: plaid.PtrString("123 Main St."), Street2: plaid.PtrString("Apt 456"), City: plaid.PtrString("San Francisco"), Region: plaid.PtrString("CA"), PostalCode: plaid.PtrString("94580"), Country: plaid.PtrString("US"), } idNumber := plaid.TransferPlatformPersonIdNumber{ Type: plaid.PtrString("us_ssn"), Value: plaid.PtrString("111223333"), } request.SetName(name) request.SetEmailAddress("ogillespie@plaid.com") request.SetPhoneNumber("+12223334444") request.SetAddress(address) request.SetIdNumber(idNumber) dob, _ := time.Parse(time.RFC3339, "2000-01-20T00:00:00Z") request.SetDateOfBirth(dob) request.SetRelationshipToOriginator(plaid.TRANSFERPLATFORMPERSONRELATIONSHIPTOORIGINATOR_BENEFICIAL_OWNER) request.SetOwnershipPercentage(plaid.PtrFloat32(50)) request.SetTitle("COO") response, _, err := client.PlaidApi.TransferPlatformPersonCreate(ctx). TransferPlatformPersonCreateRequest(*request). Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. string An ID that should be used when submitting additional requirements that are associated with this person. Response Object ```json { "person_id": "4aa32e78-0cb3-4c13-b45e-7f9f2fc709d1", "request_id": "qpCtcJz6g3fhMdJ" } ``` \=\*=\*=\*= #### /transfer/platform/requirement/submit  #### Submit additional onboarding information on behalf of an originator  Use the [/transfer/platform/requirement/submit](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformrequirementsubmit) endpoint to submit additional onboarding information that is needed by Plaid to approve or decline the originator. See [Requirement type schema documentation](https://docs.google.com/document/d/1NEQkTD0sVK50iAQi6xHigrexDUxZ4QxXqSEfV_FFTiU/) for a list of requirement types and possible values. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The client ID of the originator required, \[object\] Use the `/transfer/platform/requirement/submit` endpoint to submit a list of requirement submissions that all relate to the originator. Must contain between 1 and 50 requirement submissions. See [Requirement type schema documentation](https://docs.google.com/document/d/1NEQkTD0sVK50iAQi6xHigrexDUxZ4QxXqSEfV_FFTiU/) for a list of requirements and possible values. Max items: `50` Min items: `1` required, string The type of requirement being submitted. See [Requirement type schema documentation](https://docs.google.com/document/d/1NEQkTD0sVK50iAQi6xHigrexDUxZ4QxXqSEfV_FFTiU/) for a list of requirement types and possible values. required, string The value of the requirement, which can be a string or an object depending on the `requirement_type`. If it is an object, the object should be JSON marshaled into a string. See [Requirement type schema documentation](https://docs.google.com/document/d/1NEQkTD0sVK50iAQi6xHigrexDUxZ4QxXqSEfV_FFTiU/) for a list of requirement types and possible values. string The `person_id` of the person the requirement submission is related to. A `person_id` is returned by `/transfer/platform/person/create`. This field should not be included for requirements that are not related to a person. Format: `uuid` ```node const request: TransferPlatformRequirementSubmitRequest = { originator_client_id: "6a65dh3d1h0d1027121ak184", requirement_submissions: [ { requirement_type: "BUSINESS_NAME", value: "Owen's Widgets Inc." }, { requirement_type: "BUSINESS_EIN", value: "123-45-6789" }, { requirement_type: "BUSINESS_BANK_ACCOUNT", value: "{\"access_token\": \"\",\"account_id\": \"\"}" }, { requirement_type: "BUSINESS_ORG_TYPE", value: "LIMITED LIABILITY COMPANY" }, { requirement_type: "BUSINESS_INDUSTRY", value: "TELECOMMUNICATIONS" }, { requirement_type: "BUSINESS_ADDRESS", value: "{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 400\"}" }, { requirement_type: "BUSINESS_WEBSITE", value: "https://plaid.com" }, { requirement_type: "BUSINESS_PRODUCT_DESCRIPTION", value: "This is a sample description." }, { requirement_type: "ASSOCIATED_PEOPLE", value: "[\"8b0e3210-767a-4882-9154-89b1e4c20493\",\"6ce1022c-d2c6-416d-a587-ed5e3f9bf941\"]" }, { requirement_type: "PERSON_NAME", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "{\"given_name\": \"Jane\",\"family_name\": \"Smith\"}" }, { requirement_type: "PERSON_ID_NUMBER", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "{\"type\": \"us_ssn\",\"value\": \"123456789\"}" }, { requirement_type: "PERSON_ADDRESS", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 100\"}" }, { requirement_type: "PERSON_DOB", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "1999-12-31" }, { requirement_type: "PERSON_EMAIL", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "sample@example.com" }, { requirement_type: "PERSON_PHONE", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "+12345678909" }, { requirement_type: "PERSON_RELATIONSHIP", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "BENEFICIAL_OWNER" }, { requirement_type: "PERSON_PERCENT_OWNERSHIP", person_id: "8b0e3210-767a-4882-9154-89b1e4c20493", value: "50" }, { requirement_type: "PERSON_TITLE", person_id: "8b0e3210-767a-4882-9154-89b1e4c20493", value: "COO" } ] }; try { const response = await client.transferPlatformRequirementSubmit(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/platform/requirement/submit \ -H "Content-Type: application/json" \ -d '{ "originator_client_id": "6a65dh3d1h0d1027121ak184", "requirement_submissions": [ { "requirement_type": "BUSINESS_NAME", "value": "Owen'\''s Widgets Inc." }, { "requirement_type": "BUSINESS_EIN", "value": "123-45-6789" }, { "requirement_type": "BUSINESS_BANK_ACCOUNT", "value": "{\"access_token\": \"\",\"account_id\": \"\"}" }, { "requirement_type": "BUSINESS_ORG_TYPE", "value": "LIMITED LIABILITY COMPANY" }, { "requirement_type": "BUSINESS_INDUSTRY", "value": "TELECOMMUNICATIONS" }, { "requirement_type": "BUSINESS_ADDRESS", "value": "{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 400\"}" }, { "requirement_type": "BUSINESS_WEBSITE", "value": "https://plaid.com" }, { "requirement_type": "BUSINESS_PRODUCT_DESCRIPTION", "value": "This is a sample description." }, { "requirement_type": "ASSOCIATED_PEOPLE", "value": "[\"8b0e3210-767a-4882-9154-89b1e4c20493\",\"6ce1022c-d2c6-416d-a587-ed5e3f9bf941\"]" }, { "requirement_type": "PERSON_NAME", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "{\"given_name\": \"Jane\",\"family_name\": \"Smith\"}" }, { "requirement_type": "PERSON_ID_NUMBER", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "{\"type\": \"us_ssn\",\"value\": \"123456789\"}" }, { "requirement_type": "PERSON_ADDRESS", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 100\"}" }, { "requirement_type": "PERSON_DOB", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "1999-12-31" }, { "requirement_type": "PERSON_EMAIL", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "sample@example.com" }, { "requirement_type": "PERSON_PHONE", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "+12345678909" }, { "requirement_type": "PERSON_RELATIONSHIP", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "BENEFICIAL_OWNER" }, { "requirement_type": "PERSON_PERCENT_OWNERSHIP", "person_id": "8b0e3210-767a-4882-9154-89b1e4c20493", "value": "50" }, { "requirement_type": "PERSON_TITLE", "person_id": "8b0e3210-767a-4882-9154-89b1e4c20493", "value": "COO" } ] }' ``` ```ruby request = Plaid::TransferPlatformRequirementSubmitRequest.new( { originator_client_id: "6a65dh3d1h0d1027121ak184", requirement_submissions: [ { requirement_type: "BUSINESS_NAME", value: "Owen's Widgets Inc." }, { requirement_type: "BUSINESS_EIN", value: "123-45-6789" }, { requirement_type: "BUSINESS_BANK_ACCOUNT", value: "{\"access_token\": \"\",\"account_id\": \"\"}" }, { requirement_type: "BUSINESS_ORG_TYPE", value: "LIMITED LIABILITY COMPANY" }, { requirement_type: "BUSINESS_INDUSTRY", value: "TELECOMMUNICATIONS" }, { requirement_type: "BUSINESS_ADDRESS", value: "{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 400\"}" }, { requirement_type: "BUSINESS_WEBSITE", value: "https://plaid.com" }, { requirement_type: "BUSINESS_PRODUCT_DESCRIPTION", value: "This is a sample description." }, { requirement_type: "ASSOCIATED_PEOPLE", value: "[\"8b0e3210-767a-4882-9154-89b1e4c20493\",\"6ce1022c-d2c6-416d-a587-ed5e3f9bf941\"]" }, { requirement_type: "PERSON_NAME", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "{\"given_name\": \"Jane\",\"family_name\": \"Smith\"}" }, { requirement_type: "PERSON_ID_NUMBER", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "{\"type\": \"us_ssn\",\"value\": \"123456789\"}" }, { requirement_type: "PERSON_ADDRESS", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 100\"}" }, { requirement_type: "PERSON_DOB", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "1999-12-31" }, { requirement_type: "PERSON_EMAIL", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "sample@example.com" }, { requirement_type: "PERSON_PHONE", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "+12345678909" }, { requirement_type: "PERSON_RELATIONSHIP", person_id: "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", value: "BENEFICIAL_OWNER" }, { requirement_type: "PERSON_PERCENT_OWNERSHIP", person_id: "8b0e3210-767a-4882-9154-89b1e4c20493", value: "50" }, { requirement_type: "PERSON_TITLE", person_id: "8b0e3210-767a-4882-9154-89b1e4c20493", value: "COO" } ] } ) response = client.transfer_platform_requirement_submit(request) ``` ```java List submissions = Arrays.asList( new TransferPlatformRequirementSubmission() .requirementType("BUSINESS_NAME") .value("Owen's Widgets Inc."), new TransferPlatformRequirementSubmission() .requirementType("BUSINESS_EIN") .value("12-3456789"), new TransferPlatformRequirementSubmission() .requirementType("BUSINESS_BANK_ACCOUNT") .value("{\"access_token\": \"\", \"account_id\": \"\"}"), new TransferPlatformRequirementSubmission() .requirementType("BUSINESS_ORG_TYPE") .value("LIMITED LIABILITY COMPANY"), new TransferPlatformRequirementSubmission() .requirementType("BUSINESS_INDUSTRY") .value("TELECOMMUNICATIONS"), new TransferPlatformRequirementSubmission() .requirementType("BUSINESS_ADDRESS") .value("{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 400\"}"), new TransferPlatformRequirementSubmission() .requirementType("BUSINESS_WEBSITE") .value("https://plaid.com"), new TransferPlatformRequirementSubmission() .requirementType("BUSINESS_PRODUCT_DESCRIPTION") .value("This is a sample description."), new TransferPlatformRequirementSubmission() .requirementType("ASSOCIATED_PEOPLE") .value("[\"8b0e3210-767a-4882-9154-89b1e4c20493\",\"6ce1022c-d2c6-416d-a587-ed5e3f9bf941\"]"), new TransferPlatformRequirementSubmission() .requirementType("PERSON_NAME") .personId("6ce1022c-d2c6-416d-a587-ed5e3f9bf941") .value("{\"given_name\":\"Jane\",\"family_name\":\"Smith\"}"), new TransferPlatformRequirementSubmission() .requirementType("PERSON_ID_NUMBER") .personId("6ce1022c-d2c6-416d-a587-ed5e3f9bf941") .value("{\"type\":\"us_ssn\",\"value\":\"123456789\"}"), new TransferPlatformRequirementSubmission() .requirementType("PERSON_ADDRESS") .personId("6ce1022c-d2c6-416d-a587-ed5e3f9bf941") .value("{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 100\"}"), new TransferPlatformRequirementSubmission() .requirementType("PERSON_DOB") .personId("6ce1022c-d2c6-416d-a587-ed5e3f9bf941") .value("1999-12-31"), new TransferPlatformRequirementSubmission() .requirementType("PERSON_EMAIL") .personId("6ce1022c-d2c6-416d-a587-ed5e3f9bf941") .value("sample@example.com"), new TransferPlatformRequirementSubmission() .requirementType("PERSON_PHONE") .personId("6ce1022c-d2c6-416d-a587-ed5e3f9bf941") .value("+12345678909"), new TransferPlatformRequirementSubmission() .requirementType("PERSON_RELATIONSHIP") .personId("6ce1022c-d2c6-416d-a587-ed5e3f9bf941") .value("BENEFICIAL_OWNER"), new TransferPlatformRequirementSubmission() .requirementType("PERSON_PERCENT_OWNERSHIP") .personId("8b0e3210-767a-4882-9154-89b1e4c20493") .value("50"), new TransferPlatformRequirementSubmission() .requirementType("PERSON_TITLE") .personId("8b0e3210-767a-4882-9154-89b1e4c20493") .value("COO") ); TransferPlatformRequirementSubmitRequest request = new TransferPlatformRequirementSubmitRequest() .originatorClientId("6a65dh3d1h0d1027121ak184") .requirementSubmissions(submissions); TransferPlatformRequirementSubmitResponse response = client.transferPlatformRequirementSubmit(request); ``` ```python request = TransferPlatformRequirementSubmitRequest( requirement_submissions=[ { "requirement_type": "BUSINESS_NAME", "value": "Owen's Widgets Inc." }, { "requirement_type": "BUSINESS_EIN", "value": "123-45-6789" }, { "requirement_type": "BUSINESS_BANK_ACCOUNT", "value": "{\"access_token\": \"\",\"account_id\": \"\"}" }, { "requirement_type": "BUSINESS_ORG_TYPE", "value": "LIMITED LIABILITY COMPANY" }, { "requirement_type": "BUSINESS_INDUSTRY", "value": "TELECOMMUNICATIONS" }, { "requirement_type": "BUSINESS_ADDRESS", "value": "{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 400\"}" }, { "requirement_type": "BUSINESS_WEBSITE", "value": "https://plaid.com" }, { "requirement_type": "BUSINESS_PRODUCT_DESCRIPTION", "value": "This is a sample description." }, { "requirement_type": "ASSOCIATED_PEOPLE", "value": "[\"8b0e3210-767a-4882-9154-89b1e4c20493\",\"6ce1022c-d2c6-416d-a587-ed5e3f9bf941\"]" }, { "requirement_type": "PERSON_NAME", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "{\"given_name\": \"Jane\",\"family_name\": \"Smith\"}" }, { "requirement_type": "PERSON_ID_NUMBER", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "{\"type\": \"us_ssn\",\"value\": \"123456789\"}" }, { "requirement_type": "PERSON_ADDRESS", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 100\"}" }, { "requirement_type": "PERSON_DOB", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "1999-12-31" }, { "requirement_type": "PERSON_EMAIL", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "sample@example.com" }, { "requirement_type": "PERSON_PHONE", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "+12345678909" }, { "requirement_type": "PERSON_RELATIONSHIP", "person_id": "6ce1022c-d2c6-416d-a587-ed5e3f9bf941", "value": "BENEFICIAL_OWNER" }, { "requirement_type": "PERSON_PERCENT_OWNERSHIP", "person_id": "8b0e3210-767a-4882-9154-89b1e4c20493", "value": "50" }, { "requirement_type": "PERSON_TITLE", "person_id": "8b0e3210-767a-4882-9154-89b1e4c20493", "value": "COO" } ] ) response = client.transfer_platform_requirement_submit(request) ``` ```go request := plaid.NewTransferPlatformRequirementSubmitRequest() submissions := []plaid.TransferPlatformRequirementSubmission{ { RequirementType: plaid.PtrString("BUSINESS_NAME"), Value: plaid.PtrString("Owen's Widgets Inc."), }, { RequirementType: plaid.PtrString("BUSINESS_EIN"), Value: plaid.PtrString("123-45-6789"), }, { RequirementType: plaid.PtrString("BUSINESS_BANK_ACCOUNT"), Value: plaid.PtrString("{\"access_token\": \"\",\"account_id\": \"\"}"), }, { RequirementType: plaid.PtrString("BUSINESS_ORG_TYPE"), Value: plaid.PtrString("LIMITED LIABILITY COMPANY"), }, { RequirementType: plaid.PtrString("BUSINESS_INDUSTRY"), Value: plaid.PtrString("TELECOMMUNICATIONS"), }, { RequirementType: plaid.PtrString("BUSINESS_ADDRESS"), Value: plaid.PtrString("{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 400\"}"), }, { RequirementType: plaid.PtrString("BUSINESS_WEBSITE"), Value: plaid.PtrString("https://plaid.com"), }, { RequirementType: plaid.PtrString("BUSINESS_PRODUCT_DESCRIPTION"), Value: plaid.PtrString("This is a sample description."), }, { RequirementType: plaid.PtrString("ASSOCIATED_PEOPLE"), Value: plaid.PtrString("[\"8b0e3210-767a-4882-9154-89b1e4c20493\",\"6ce1022c-d2c6-416d-a587-ed5e3f9bf941\"]"), }, { RequirementType: plaid.PtrString("PERSON_NAME"), PersonId: plaid.PtrString("6ce1022c-d2c6-416d-a587-ed5e3f9bf941"), Value: plaid.PtrString("{\"given_name\": \"Jane\",\"family_name\": \"Smith\"}"), }, { RequirementType: plaid.PtrString("PERSON_ID_NUMBER"), PersonId: plaid.PtrString("6ce1022c-d2c6-416d-a587-ed5e3f9bf941"), Value: plaid.PtrString("{\"type\": \"us_ssn\",\"value\": \"123456789\"}"), }, { RequirementType: plaid.PtrString("PERSON_ADDRESS"), PersonId: plaid.PtrString("6ce1022c-d2c6-416d-a587-ed5e3f9bf941"), Value: plaid.PtrString("{\"city\":\"San Francisco\",\"country\":\"US\",\"postal_code\":\"94105\",\"region\":\"CA\",\"street\":\"123 Market St\",\"street2\":\"Suite 100\"}"), }, { RequirementType: plaid.PtrString("PERSON_DOB"), PersonId: plaid.PtrString("6ce1022c-d2c6-416d-a587-ed5e3f9bf941"), Value: plaid.PtrString("1999-12-31"), }, { RequirementType: plaid.PtrString("PERSON_EMAIL"), PersonId: plaid.PtrString("6ce1022c-d2c6-416d-a587-ed5e3f9bf941"), Value: plaid.PtrString("sample@example.com"), }, { RequirementType: plaid.PtrString("PERSON_PHONE"), PersonId: plaid.PtrString("6ce1022c-d2c6-416d-a587-ed5e3f9bf941"), Value: plaid.PtrString("+12345678909"), }, { RequirementType: plaid.PtrString("PERSON_RELATIONSHIP"), PersonId: plaid.PtrString("6ce1022c-d2c6-416d-a587-ed5e3f9bf941"), Value: plaid.PtrString("BENEFICIAL_OWNER"), }, { RequirementType: plaid.PtrString("PERSON_PERCENT_OWNERSHIP"), PersonId: plaid.PtrString("8b0e3210-767a-4882-9154-89b1e4c20493"), Value: plaid.PtrString("50"), }, { RequirementType: plaid.PtrString("PERSON_TITLE"), PersonId: plaid.PtrString("8b0e3210-767a-4882-9154-89b1e4c20493"), Value: plaid.PtrString("COO"), }, } request.SetOriginatorClientId("6a65dh3d1h0d1027121ak184") request.SetRequirementSubmissions(submissions) response, _, err := client.PlaidApi.TransferPlatformRequirementSubmit(ctx). TransferPlatformRequirementSubmitRequest(*request). Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/platform/document/submit  #### Upload documentation on behalf of an originator  Use the [/transfer/platform/document/submit](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformdocumentsubmit) endpoint to upload documents requested by Plaid to verify an originator's onboarding information. Unlike other endpoints, this one requires `multipart/form-data` as the content type. This endpoint is also not included in the Plaid client libraries. #### Request fields  required, string The client ID of the originator required, string The path to the document file to upload required, string The type of requirement this document fulfills string The `person_id` of the person the requirement submission is related to. A `person_id` is returned by `/transfer/platform/person/create`. This field should not be included for requirements that are not related to a person. Format: `uuid` ```node import fs from 'fs'; import fetch from 'node-fetch'; import FormData from 'form-data'; const form = new FormData(); form.append('originator_client_id', '6a65dh3d1h0d1027121ak184'); form.append('document_submission', fs.createReadStream('/path/to/sample/file.txt')); form.append('requirement_type', 'BUSINESS_ADDRESS_VALIDATION'); const res = await fetch(`https://sandbox.plaid.com/transfer/platform/document/submit`, { method: 'POST', headers: { 'Plaid-Client-ID': '', 'Plaid-Secret': '', ...form.getHeaders(), }, body: form, }); const data = await res.json(); ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/platform/document/submit \ -H "Content-Type: multipart/form-data" \ -H "Plaid-Client-ID: " \ -H "Plaid-Secret: " \ -F "originator_client_id=6a65dh3d1h0d1027121ak184" \ -F "document_submission=@/path/to/sample/file.txt" \ -F "requirement_type=BUSINESS_ADDRESS_VALIDATION" ``` ```ruby require 'net/http' require 'uri' require 'openssl' uri = URI.parse("https://sandbox.plaid.com/transfer/platform/document/submit") request = Net::HTTP::Post.new(uri) request["Plaid-Client-ID"] = '' request["Plaid-Secret"] = '' form_data = [[ 'document_submission', File.open('/path/to/sample/file.txt'), { filename: 'file.txt', content_type: 'text/plain' } ], ['originator_client_id', '6a65dh3d1h0d1027121ak184'], ['requirement_type', 'BUSINESS_ADDRESS_VALIDATION']] request.set_form form_data, 'multipart/form-data' req_options = { use_ssl: uri.scheme == 'https' } response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http| http.request(request) end ``` ```java import java.io.File; import okhttp3.*; OkHttpClient client = new OkHttpClient(); MediaType mediaType = MediaType.parse("text/plain"); RequestBody fileBody = RequestBody.create(new File("/path/to/sample/file.txt"), mediaType); MultipartBody requestBody = new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart("originator_client_id", "6a65dh3d1h0d1027121ak184") .addFormDataPart("requirement_type", "BUSINESS_ADDRESS_VALIDATION") .addFormDataPart("document_submission", "file.txt", fileBody) .build(); Request request = new Request.Builder() .url("https://sandbox.plaid.com/transfer/platform/document/submit") .addHeader("Plaid-Client-ID", "") .addHeader("Plaid-Secret", "") .post(requestBody) .build(); Response response = client.newCall(request).execute(); ``` ```python import requests url = "https://sandbox.plaid.com/transfer/platform/document/submit" headers = { 'Plaid-Client-ID': '', 'Plaid-Secret': '' } data = { 'originator_client_id': '6a65dh3d1h0d1027121ak184', 'requirement_type': 'BUSINESS_ADDRESS_VALIDATION' } files = { 'document_submission': ('file.txt', open('/path/to/sample/file.txt', 'rb'), 'text/plain') } response = requests.post(url, headers=headers, data=data, files=files) ``` ```go package main import ( "bytes" "mime/multipart" "net/http" "os" ) func main() { var buf bytes.Buffer writer := multipart.NewWriter(&buf) writer.WriteField("originator_client_id", "6a65dh3d1h0d1027121ak184") writer.WriteField("requirement_type", "BUSINESS_ADDRESS_VALIDATION") file, _ := os.Open("/path/to/sample/file.txt") defer file.Close() part, _ := writer.CreateFormFile("document_submission", "file.txt") io.Copy(part, file) writer.Close() req, _ := http.NewRequest("POST", "https://sandbox.plaid.com/transfer/platform/document/submit", &buf) req.Header.Set("Content-Type", writer.FormDataContentType()) req.Header.Set("Plaid-Client-ID", "") req.Header.Set("Plaid-Secret", "") http.DefaultClient.Do(req) } ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. ```json { "request_id": "YkP5Aq2x9LkZQb7" } ``` \=\*=\*=\*= #### /transfer/originator/get  #### Get status of an originator's onboarding  The [/transfer/originator/get](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorget) endpoint gets status updates for an originator's onboarding process. This information is also available via the Transfer page on the Plaid dashboard. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Client ID of the end customer (i.e. the originator). ```node const request: TransferOriginatorGetRequest = { originator_client_id: '6a65dh3d1h0d1027121ak184', }; try { const response = await client.transferOriginatorGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/originator/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "originator_client_id": "6a65dh3d1h0d1027121ak184", }' ``` ```ruby request = Plaid::TransferOriginatorGetRequest.new( { originator_client_id: '6a65dh3d1h0d1027121ak184', } ) response = client.transfer_originator_get(request) ``` ```java TransferOriginatorGetRequest request = new TransferOriginatorGetRequest() .originatorClientId("6a65dh3d1h0d1027121ak184"); Response response = client() .transferOriginatorGet(request) .execute(); ``` ```python request = TransferOriginatorGetRequest( originator_client_id='6a65dh3d1h0d1027121ak184', ) response = client.transfer_originator_get(request) ``` ```go request := plaid.NewTransferOriginatorGetRequest( "6a65dh3d1h0d1027121ak184", ) response, _, err := client.PlaidApi.TransferOriginatorGet(ctx).TransferOriginatorGetRequest(*request).Execute() ``` #### Response fields  object Originator and their status. string Originator’s client ID. string Originator’s diligence status. Possible values: `not_submitted`, `submitted`, `under_review`, `approved`, `denied`, `more_information_required` string The company name of the end customer. \[object\] List of outstanding requirements that must be submitted before Plaid can approve the originator. Only populated when `transfer_diligence_status` is `more_information_required`. string The type of requirement. nullable, string UUID of the person associated with the requirement. Only present for individual-scoped requirements. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "originator": { "client_id": "6a65dh3d1h0d1027121ak184", "transfer_diligence_status": "approved", "company_name": "Plaid" }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/originator/list  #### Get status of all originators' onboarding  The [/transfer/originator/list](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorlist) endpoint gets status updates for all of your originators' onboarding. This information is also available via the Plaid dashboard. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. integer The maximum number of originators to return. Maximum: `25` Minimum: `1` Default: `25` integer The number of originators to skip before returning results. Minimum: `0` Default: `0` ```node const request: TransferOriginatorListRequest = { count: 14, offset: 2, }; try { const response = await client.transferOriginatorList(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/originator/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "count": 14, "offset": 2, }' ``` ```ruby request = Plaid::TransferOriginatorListRequest.new( { count: 14, offset: 2, } ) response = client.transfer_originator_list(request) ``` ```java TransferOriginatorListRequest request = new TransferOriginatorListRequest() .count(14) .offset(2); Response response = client() .transferOriginatorList(request) .execute(); ``` ```python request = TransferOriginatorListRequest( count=14, offset=2, ) response = client.transfer_originator_list(request) ``` ```go request := plaid.NewTransferOriginatorListRequest( 14, 2, ) response, _, err := client.PlaidApi.TransferOriginatorList(ctx).TransferOriginatorListRequest(*request).Execute() ``` #### Response fields  \[object\] string Originator’s client ID. string Originator’s diligence status. Possible values: `not_submitted`, `submitted`, `under_review`, `approved`, `denied`, `more_information_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "originators": [ { "client_id": "6a65dh3d1h0d1027121ak184", "transfer_diligence_status": "approved" }, { "client_id": "8g89as4d2k1d9852938ba019", "transfer_diligence_status": "denied" } ], "request_id": "4zlKapIkTm8p5KM" } ``` \=\*=\*=\*= #### /transfer/originator/funding\_account/create  #### Create a new funding account for an originator  Use the [/transfer/originator/funding\_account/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorfunding_accountcreate) endpoint to create a new funding account for the originator. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The Plaid client ID of the transfer originator. required, object The originator's funding account, linked with Plaid Link or `/transfer/migrate_account`. required, string The access token associated with the Item data is being requested for. required, string The Plaid `account_id` for the newly created Item. string The name for the funding account that is displayed in the Plaid dashboard. ```node const request: TransferOriginatorFundingAccountCreateRequest = { originator_client_id: '6a65dh3d1h0d1027121ak184', funding_account: { access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', display_name: "New Funding Account", }, }; try { const response = await client.transferOriginatorFundingAccountCreate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/originator/funding_account/create \ -H 'Content-Type: application/json' \ -d '{ "originator_client_id": "6a65dh3d1h0d1027121ak184", "funding_account": { "access_token": "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "display_name": "New Funding Account" } }' ``` ```ruby request = Plaid::TransferOriginatorFundingAccountCreateRequest.new( { originator_client_id: '6a65dh3d1h0d1027121ak184', funding_account: { access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', display_name: 'New Funding Account', }, } ) response = client.transfer_originator_funding_account_create(request) ``` ```java TransferFundingAccount fundingAccount = new TransferFundingAccount() .accessToken("access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175") .accountId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr") .displayName("New FundingAccount"); TransferOriginatorFundingAccountCreateRequest request = new TransferOriginatorFundingAccountCreateRequest() .originatorClientId("6a65dh3d1h0d1027121ak184") .fundingAccount(fundingAccount); Response response = client() .transferOriginatorFundingAccountCreate(request) .execute(); ``` ```python request = TransferOriginatorFundingAccountCreateRequest( originator_client_id="6a65dh3d1h0d1027121ak184", funding_account=TransferFundingAccount( access_token="access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", account_id="3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", display_name="New Funding Account", ), ) response = client.transfer_originator_funding_account_create(request) ``` ```go request := plaid.NewTransferOriginatorFundingAccountCreateRequest( "6a65dh3d1h0d1027121ak184", plaid.NewTransferFundingAccount( "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "New Funding Account", ), ) response, _, err := client.PlaidApi.TransferOriginatorFundingAccountCreate(ctx).TransferOriginatorFundingAccountCreateRequest(*request).Execute() ``` #### Response fields  string The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "request_id": "saKrIBuEB9qJZno" } ``` --- # API - Reading Transfers | Plaid Docs Reading Transfers and Transfer events  ====================================== #### API reference for Transfer read and Transfer event endpoints and webhooks  For how-to guidance, see the [Transfer events documentation](https://plaid.com/docs/transfer/reconciling-transfers/index.html.md) . | Reading Transfers | | | --- | --- | | [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) | Retrieve information about a transfer | | [/transfer/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferlist) | Retrieve a list of transfers and their statuses | | [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) | Retrieve a list of transfer events | | [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) | Sync transfer events | | [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) | Retrieve information about a sweep | | [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) | Retrieve a list of sweeps | | Webhooks | | | --- | --- | | [TRANSFER\_EVENTS\_UPDATE](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfer_events_update) | New transfer events available | ### Endpoints  \=\*=\*=\*= #### /transfer/get  #### Retrieve a transfer  The [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) endpoint fetches information about the transfer corresponding to the given `transfer_id` or `authorization_id`. One of `transfer_id` or `authorization_id` must be populated but not both. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Plaid’s unique identifier for a transfer. string Plaid’s unique identifier for a transfer authorization. ```node const request: TransferGetRequest = { transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', }; try { const response = await plaidClient.transferGet(request); const transfer = response.data.transfer; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9" }' ``` ```ruby request = Plaid::TransferGetRequest.new({ transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9' }) response = client.transfer_get(request) ``` ```java TransferGetRequest request = new TransferGetRequest() .transferId("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9"); Response response = client() .transferGet(request) .execute(); Transfer transfer = response.body().getTransfer(); ``` ```python request = TransferGetRequest(transfer_id='460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9') response = client.transfer_get(request) transfer = response['transfer'] ``` ```go request := plaid.NewTransferGetRequest( "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9" ) response, _, err := client.PlaidApi.TransferGet(ctx).TransferGetRequest(*request).Execute() ``` #### Response fields  object Represents a transfer within the Transfers API. string Plaid’s unique identifier for a transfer. string Plaid’s unique identifier for a transfer authorization. string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. nullable, string The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `debit`, `credit` object The legal name and other information for the account holder. string The user's legal name. nullable, string The user's phone number. nullable, string The user's email address. nullable, object The address associated with the account holder. nullable, string The street number and name (i.e., "100 Market St."). nullable, string Ex. "San Francisco" nullable, string The state or province (e.g., "CA"). nullable, string The postal code (e.g., "94103"). nullable, string A two-letter country code (e.g., "US"). string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. string The description of the transfer. string The datetime when this transfer was created. This will be of the form `2006-01-02T15:04:05Z` Format: `date-time` string The status of the transfer. `pending`: A new transfer was created; it is in the pending state. `posted`: The transfer has been successfully submitted to the payment network. `settled`: The transfer was successfully completed by the payment network. Note that funds from received debits are not available to be moved out of the Ledger until the transfer reaches `funds_available` status. For credit transactions, `settled` means the funds have been delivered to the receiving bank account. This is the terminal state of a successful credit transfer. `funds_available`: Funds from the transfer have been released from hold and applied to the ledger's available balance. (Only applicable to ACH debits.) This is the terminal state of a successful debit transfer. `cancelled`: The transfer was cancelled by the client. This is the terminal state of a cancelled transfer. `failed`: The transfer failed, no funds were moved. This is the terminal state of a failed transfer. `returned`: A posted transfer was returned. This is the terminal state of a returned transfer. Possible values: `pending`, `posted`, `settled`, `funds_available`, `cancelled`, `failed`, `returned` nullable, string The status of the sweep for the transfer. `unswept`: The transfer hasn't been swept yet. `swept`: The transfer was swept to the sweep account. `swept_settled`: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. `return_swept`: The transfer was returned, funds were pulled back or pushed back to the sweep account. `null`: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept) Possible values: `null`, `unswept`, `swept`, `swept_settled`, `return_swept` string The network or rails used for the transfer. For transfers submitted as `ach` or `same-day-ach`, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted as `same-day-ach`, the Same Day ACH cutoff is 3:00 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail. For transfers submitted as `rtp`, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as `rtp` and the counterparty account is not eligible for RTP, the `/transfer/authorization/create` request will fail with an `INVALID_FIELD` error code. To pre-check to determine whether a counterparty account can support RTP, call `/transfer/capabilities/get` before calling `/transfer/authorization/create`. Wire transfers are currently in early availability. To request access to `wire` as a payment network, contact your Account Manager. For transfers submitted as `wire`, the `type` must be `credit`; wire debits are not supported. The cutoff to submit a wire payment is 6:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail. Possible values: `ach`, `same-day-ach`, `rtp`, `wire` nullable, object Information specific to wire transfers. nullable, string Additional information from the wire originator to the beneficiary. Max 140 characters. nullable, string The fee amount deducted from the original transfer during a wire return, if applicable. boolean When `true`, you can still cancel this transfer. nullable, object The failure reason if the event type for a transfer is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the transfer status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . string A human-readable description of the reason for the failure or reversal. nullable, object The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters string The currency of the transfer amount, e.g. "USD" nullable, string The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD. Format: `date` nullable, string The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD. Format: `date` deprecated, nullable, string Deprecated for Plaid Ledger clients, use `expected_funds_available_date` instead. Format: `date` nullable, string The expected date when funds from a transfer will be made available and can be withdrawn from the associated ledger balance, assuming the debit does not return before this date. If the transfer does return before this date, this field will be null. Only applies to debit transfers. This will be of the form YYYY-MM-DD. Format: `date` nullable, string The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a [Platform customer](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) . \[object\] A list of refunds associated with this transfer. string Plaid’s unique identifier for a refund. string The ID of the transfer to refund. string The amount of the refund (decimal string with two digits of precision e.g. "10.00"). string The status of the refund. `pending`: A new refund was created; it is in the pending state. `posted`: The refund has been successfully submitted to the payment network. `settled`: Credits have been refunded to the Plaid linked account. `cancelled`: The refund was cancelled by the client. `failed`: The refund has failed. `returned`: The refund was returned. Possible values: `pending`, `posted`, `cancelled`, `failed`, `settled`, `returned` nullable, object The failure reason if the event type for a refund is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the refund status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the refund status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . This field is deprecated in favor of the more versatile `failure_code`, which encompasses non-ACH failure codes as well. string A human-readable description of the reason for the failure or reversal. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The datetime when this refund was created. This will be of the form `2006-01-02T15:04:05Z` Format: `date-time` nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. nullable, string The id of the recurring transfer if this transfer belongs to a recurring transfer. \[object\] The expected sweep settlement schedule of this transfer, assuming this transfer is not `returned`. Only applies to ACH debit transfers. string The settlement date of a sweep for this transfer. Format: `date` string The accumulated amount that has been swept by `sweep_settlement_date`. deprecated, nullable, string This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023. Specifies the source of funds for the transfer. Only valid for `credit` transfers, and defaults to `sweep` if not specified. This field is not specified for `debit` transfers. `sweep` - Sweep funds from your funding account `prefunded_rtp_credits` - Use your prefunded RTP credit balance with Plaid `prefunded_ach_credits` - Use your prefunded ACH credit balance with Plaid Possible values: `sweep`, `prefunded_rtp_credits`, `prefunded_ach_credits`, `null` string The amount to deduct from `transfer.amount` and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be value greater than 0 and less than or equal to the `transfer.amount`. nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "transfer": { "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "ach_class": "ppd", "amount": "12.34", "cancellable": true, "created": "2020-08-06T17:27:15Z", "description": "Desc", "guarantee_decision": null, "guarantee_decision_rationale": null, "failure_reason": { "failure_code": "R13", "description": "Invalid ACH routing number" }, "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586", "metadata": { "key1": "value1", "key2": "value2" }, "network": "ach", "origination_account_id": "", "originator_client_id": null, "refunds": [], "status": "pending", "type": "credit", "iso_currency_code": "USD", "standard_return_window": "2020-08-07", "unauthorized_return_window": "2020-10-07", "expected_settlement_date": "2020-08-04", "user": { "email_address": "acharleston@email.com", "legal_name": "Anne Charleston", "phone_number": "510-555-0128", "address": { "street": "123 Main St.", "city": "San Francisco", "region": "CA", "postal_code": "94053", "country": "US" } }, "recurring_transfer_id": null, "credit_funds_source": "sweep", "facilitator_fee": "1.23", "network_trace_id": null }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/list  #### List transfers  Use the [/transfer/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferlist) endpoint to see a list of all your transfers and their statuses. Results are paginated; use the `count` and `offset` query parameters to retrieve the desired transfers. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The start `created` datetime of transfers to list. This should be in RFC 3339 format (i.e. `2019-12-06T22:35:49Z`) Format: `date-time` string The end `created` datetime of transfers to list. This should be in RFC 3339 format (i.e. `2019-12-06T22:35:49Z`) Format: `date-time` integer The maximum number of transfers to return. Minimum: `1` Maximum: `25` Default: `25` integer The number of transfers to skip before returning results. Default: `0` Minimum: `0` string Filter transfers to only those with the specified originator client. string Filter transfers to only those with the specified `funding_account_id`. ```node const request: TransferListRequest = { start_date: '2019-12-06T22:35:49Z', end_date: '2019-12-12T22:35:49Z', count: 14, offset: 2, origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460', }; try { const response = await plaidClient.transferList(request); const transfers = response.data.transfers; for (const transfer of transfers) { // iterate through transfers } } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "start_date": "2019-12-06T22:35:49Z", "end_date": "2019-12-12T22:35:49Z", "count": 14, "offset": 2, "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460" }' ``` ```ruby require 'time' request = Plaid::TransferListRequest.new( { count: 14, start_date: Time.parse("2019-12-06T22:35:49Z"), end_date: Time.parse("2019-12-12T22:35:49Z"), offset: 2, origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460' } ) response = client.transfer_list(request) response.transfers.each do |tr| # iterate through transfers end ``` ```java import java.time.OffsetDateTime; OffsetDateTime startDate = OffsetDateTime.parse("2019-12-06T22:35:49+00:00"); OffsetDateTime endDate = OffsetDateTime.parse("2019-12-12T22:35:49+00:00"); TransferListRequest request = new TransferListRequest() .count(14) .startDate(startDate) .endDate(endDate) .offset(2) .originationAccountId("8945fedc-e703-463d-86b1-dc0607b55460"); Response response = client() .transferList(request) .execute(); List transfers = response.body().getTransfers(); for (Transfer transfer : transfers) { // iterate through transfers } ``` ```python import datetime request = TransferListRequest( start_date=datetime.datetime(2019, 12, 6, 22, 35, 49, tzinfo=datetime.timezone.utc), end_date=datetime.datetime(2019, 12, 12, 22, 35, 49, tzinfo=datetime.timezone.utc), count=14, offset=2, origination_account_id='8945fedc-e703-463d-86b1-dc0607b55460' ) response = client.transfer_list(request) transfers = response['transfers'] for transfer in transfers: # iterate through transfers ``` ```go import ( "time" ) request := plaid.NewTransferListRequest() request.SetStartDate(time.Date(2019, time.December, 6, 22, 35, 49, 0, time.UTC)) request.SetEndDate(time.Date(2019, time.December, 12, 22, 35, 49, 0, time.UTC)) request.SetCount(14) request.SetOffset(2) request.SetOriginationAccountId("8945fedc-e703-463d-86b1-dc0607b55460") response, _, err := client.PlaidApi.TransferList(ctx).TransferListRequest(*request).Execute() ``` #### Response fields  \[object\] string Plaid’s unique identifier for a transfer. string Plaid’s unique identifier for a transfer authorization. string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. nullable, string The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `debit`, `credit` object The legal name and other information for the account holder. string The user's legal name. nullable, string The user's phone number. nullable, string The user's email address. nullable, object The address associated with the account holder. nullable, string The street number and name (i.e., "100 Market St."). nullable, string Ex. "San Francisco" nullable, string The state or province (e.g., "CA"). nullable, string The postal code (e.g., "94103"). nullable, string A two-letter country code (e.g., "US"). string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. string The description of the transfer. string The datetime when this transfer was created. This will be of the form `2006-01-02T15:04:05Z` Format: `date-time` string The status of the transfer. `pending`: A new transfer was created; it is in the pending state. `posted`: The transfer has been successfully submitted to the payment network. `settled`: The transfer was successfully completed by the payment network. Note that funds from received debits are not available to be moved out of the Ledger until the transfer reaches `funds_available` status. For credit transactions, `settled` means the funds have been delivered to the receiving bank account. This is the terminal state of a successful credit transfer. `funds_available`: Funds from the transfer have been released from hold and applied to the ledger's available balance. (Only applicable to ACH debits.) This is the terminal state of a successful debit transfer. `cancelled`: The transfer was cancelled by the client. This is the terminal state of a cancelled transfer. `failed`: The transfer failed, no funds were moved. This is the terminal state of a failed transfer. `returned`: A posted transfer was returned. This is the terminal state of a returned transfer. Possible values: `pending`, `posted`, `settled`, `funds_available`, `cancelled`, `failed`, `returned` nullable, string The status of the sweep for the transfer. `unswept`: The transfer hasn't been swept yet. `swept`: The transfer was swept to the sweep account. `swept_settled`: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. `return_swept`: The transfer was returned, funds were pulled back or pushed back to the sweep account. `null`: The transfer will never be swept (e.g. if the transfer is cancelled or returned before being swept) Possible values: `null`, `unswept`, `swept`, `swept_settled`, `return_swept` string The network or rails used for the transfer. For transfers submitted as `ach` or `same-day-ach`, the Standard ACH cutoff is 8:30 PM Eastern Time. For transfers submitted as `same-day-ach`, the Same Day ACH cutoff is 3:00 PM Eastern Time. It is recommended to send the request 15 minutes prior to the cutoff to ensure that it will be processed in time for submission before the cutoff. If the transfer is processed after this cutoff but before the Standard ACH cutoff, it will be sent over Standard ACH rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable. The transaction limit for a Same Day ACH transfer is $1,000,000. Authorization requests sent with an amount greater than $1,000,000 will fail. For transfers submitted as `rtp`, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as `rtp` and the counterparty account is not eligible for RTP, the `/transfer/authorization/create` request will fail with an `INVALID_FIELD` error code. To pre-check to determine whether a counterparty account can support RTP, call `/transfer/capabilities/get` before calling `/transfer/authorization/create`. Wire transfers are currently in early availability. To request access to `wire` as a payment network, contact your Account Manager. For transfers submitted as `wire`, the `type` must be `credit`; wire debits are not supported. The cutoff to submit a wire payment is 6:30 PM Eastern Time on a business day; wires submitted after that time will be processed on the next business day. The transaction limit for a wire is $999,999.99. Authorization requests sent with an amount greater than $999,999.99 will fail. Possible values: `ach`, `same-day-ach`, `rtp`, `wire` nullable, object Information specific to wire transfers. nullable, string Additional information from the wire originator to the beneficiary. Max 140 characters. nullable, string The fee amount deducted from the original transfer during a wire return, if applicable. boolean When `true`, you can still cancel this transfer. nullable, object The failure reason if the event type for a transfer is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the transfer status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . string A human-readable description of the reason for the failure or reversal. nullable, object The Metadata object is a mapping of client-provided string fields to any string value. The following limitations apply: The JSON values must be Strings (no nested JSON objects allowed) Only ASCII characters may be used Maximum of 50 key/value pairs Maximum key length of 40 characters Maximum value length of 500 characters string The currency of the transfer amount, e.g. "USD" nullable, string The date 3 business days from settlement date indicating the following ACH returns can no longer happen: R01, R02, R03, R29. This will be of the form YYYY-MM-DD. Format: `date` nullable, string The date 61 business days from settlement date indicating the following ACH returns can no longer happen: R05, R07, R10, R11, R51, R33, R37, R38, R51, R52, R53. This will be of the form YYYY-MM-DD. Format: `date` deprecated, nullable, string Deprecated for Plaid Ledger clients, use `expected_funds_available_date` instead. Format: `date` nullable, string The expected date when funds from a transfer will be made available and can be withdrawn from the associated ledger balance, assuming the debit does not return before this date. If the transfer does return before this date, this field will be null. Only applies to debit transfers. This will be of the form YYYY-MM-DD. Format: `date` nullable, string The Plaid client ID that is the originator of this transfer. Only present if created on behalf of another client as a [Platform customer](https://plaid.com/docs/transfer/application/index.html.md#originators-vs-platforms) . \[object\] A list of refunds associated with this transfer. string Plaid’s unique identifier for a refund. string The ID of the transfer to refund. string The amount of the refund (decimal string with two digits of precision e.g. "10.00"). string The status of the refund. `pending`: A new refund was created; it is in the pending state. `posted`: The refund has been successfully submitted to the payment network. `settled`: Credits have been refunded to the Plaid linked account. `cancelled`: The refund was cancelled by the client. `failed`: The refund has failed. `returned`: The refund was returned. Possible values: `pending`, `posted`, `cancelled`, `failed`, `settled`, `returned` nullable, object The failure reason if the event type for a refund is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the refund status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the refund status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . This field is deprecated in favor of the more versatile `failure_code`, which encompasses non-ACH failure codes as well. string A human-readable description of the reason for the failure or reversal. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The datetime when this refund was created. This will be of the form `2006-01-02T15:04:05Z` Format: `date-time` nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. nullable, string The id of the recurring transfer if this transfer belongs to a recurring transfer. \[object\] The expected sweep settlement schedule of this transfer, assuming this transfer is not `returned`. Only applies to ACH debit transfers. string The settlement date of a sweep for this transfer. Format: `date` string The accumulated amount that has been swept by `sweep_settlement_date`. deprecated, nullable, string This field is now deprecated. You may ignore it for transfers created on and after 12/01/2023. Specifies the source of funds for the transfer. Only valid for `credit` transfers, and defaults to `sweep` if not specified. This field is not specified for `debit` transfers. `sweep` - Sweep funds from your funding account `prefunded_rtp_credits` - Use your prefunded RTP credit balance with Plaid `prefunded_ach_credits` - Use your prefunded ACH credit balance with Plaid Possible values: `sweep`, `prefunded_rtp_credits`, `prefunded_ach_credits`, `null` string The amount to deduct from `transfer.amount` and distribute to the platform’s Ledger balance as a facilitator fee (decimal string with two digits of precision e.g. "10.00"). The remainder will go to the end-customer’s Ledger balance. This must be value greater than 0 and less than or equal to the `transfer.amount`. nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "transfers": [ { "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "ach_class": "ppd", "amount": "12.34", "cancellable": true, "created": "2019-12-09T17:27:15Z", "description": "Desc", "guarantee_decision": null, "guarantee_decision_rationale": null, "failure_reason": { "failure_code": "R13", "description": "Invalid ACH routing number" }, "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "authorization_id": "c9f90aa1-2949-c799-e2b6-ea05c89bb586", "metadata": { "key1": "value1", "key2": "value2" }, "network": "ach", "origination_account_id": "", "originator_client_id": null, "refunds": [], "status": "pending", "type": "credit", "iso_currency_code": "USD", "standard_return_window": "2020-08-07", "unauthorized_return_window": "2020-10-07", "expected_settlement_date": "2020-08-04", "user": { "email_address": "acharleston@email.com", "legal_name": "Anne Charleston", "phone_number": "510-555-0128", "address": { "street": "123 Main St.", "city": "San Francisco", "region": "CA", "postal_code": "94053", "country": "US" } }, "recurring_transfer_id": null, "credit_funds_source": "sweep", "facilitator_fee": "1.23", "network_trace_id": null } ], "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/event/list  #### List transfer events  Use the [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) endpoint to get a list of transfer events based on specified filter criteria. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The start `created` datetime of transfers to list. This should be in RFC 3339 format (i.e. `2019-12-06T22:35:49Z`) Format: `date-time` string The end `created` datetime of transfers to list. This should be in RFC 3339 format (i.e. `2019-12-06T22:35:49Z`) Format: `date-time` string Plaid’s unique identifier for a transfer. string The account ID to get events for all transactions to/from an account. string The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into your origination account; a `credit` indicates a transfer of money out of your origination account. Possible values: `debit`, `credit`, `null` \[string\] Filter events by event type. Possible values: `pending`, `cancelled`, `failed`, `posted`, `settled`, `funds_available`, `returned`, `swept`, `swept_settled`, `return_swept`, `sweep.pending`, `sweep.posted`, `sweep.settled`, `sweep.returned`, `sweep.failed`, `sweep.funds_available`, `refund.pending`, `refund.cancelled`, `refund.failed`, `refund.posted`, `refund.settled`, `refund.returned`, `refund.swept`, `refund.return_swept` string Plaid’s unique identifier for a sweep. integer The maximum number of transfer events to return. If the number of events matching the above parameters is greater than `count`, the most recent events will be returned. Default: `25` Maximum: `25` Minimum: `1` integer The offset into the list of transfer events. When `count`\=25 and `offset`\=0, the first 25 events will be returned. When `count`\=25 and `offset`\=25, the next 25 events will be returned. Default: `0` Minimum: `0` string Filter transfer events to only those with the specified originator client. string Filter transfer events to only those with the specified `funding_account_id`. ```node const request: TransferEventListRequest = { start_date: '2019-12-06T22:35:49Z', end_date: '2019-12-12T22:35:49Z', transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', transfer_type: 'credit', event_types: ['pending', 'posted'], count: 14, offset: 2, origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460', }; try { const response = await plaidClient.transferEventList(request); const events = response.data.transfer_events; for (const event of events) { // iterate through events } } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/event/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "start_date": "2019-12-06T22:35:49Z", "end_date": "2019-12-12T22:35:49Z", "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "transfer_type": "credit", "event_types": "["pending", "posted"]", "count": 14, "offset": 2, "origination_account_id": "8945fedc-e703-463d-86b1-dc0607b55460" }' ``` ```ruby require 'time' request = Plaid::TransferEventListRequest.new( { start_date: Time.parse('2019-12-06T22:35:49Z'), end_date: Time.parse('2019-12-12T22:35:49Z'), transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', transfer_type: 'credit', event_types: ['pending', 'posted'], count: 14, offset: 2, origination_account_id: '8945fedc-e703-463d-86b1-dc0607b55460' } ) response = client.transfer_event_list(request) response.transfer_events.each do |event| # iterate through events end ``` ```java import java.time.OffsetDateTime; import java.util.ArrayList; import java.util.List; import com.plaid.client.model.TransferEventListTransferType; import com.plaid.client.model.TransferEventType; OffsetDateTime startDate = OffsetDateTime.parse("2019-12-06T22:35:49+00:00"); OffsetDateTime endDate = OffsetDateTime.parse("2019-12-12T22:35:49+00:00"); TransferEventListTransferType transferType = new TransferEventListTransferType("credit"); List eventTypes = new ArrayList(); eventTypes.add("pending"); eventTypes.add("posted"); TransferEventListRequest request = new TransferEventListRequest() .transferId("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9") .startDate(startDate) .endDate(endDate) .accountId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr") .transferType(transferType) .eventTypes(eventTypes) .count(14) .offset(2) .originationAccountId("8945fedc-e703-463d-86b1-dc0607b55460"); Response response = client() .transferEventList(request) .execute(); List transferEvents = response.body().getTransferEvents(); for (TransferEvent e : transferEvents) { // iterate through events } ``` ```python import datetime from plaid.model.transfer_event_list_transfer_type import TransferEventListTransferType from plaid.model.transfer_event_type import TransferEventType request = TransferEventListRequest( start_date=datetime.datetime(2019, 12, 6, 22, 35, 49, tzinfo=datetime.timezone.utc), end_date=datetime.datetime(2019, 12, 12, 22, 35, 49, tzinfo=datetime.timezone.utc), transfer_id='460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', account_id='3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', transfer_type=TransferEventListTransferType('credit'), event_types=TransferEventType(['pending', 'posted']), count=14, offset=2, origination_account_id='8945fedc-e703-463d-86b1-dc0607b55460' ) response = client.transfer_event_list(request) events = response['transfer_events'] for event in events: # iterate through events ``` ```go request := plaid.NewTransferEventListRequest() request.SetStartDate(time.Date(2019, time.December, 6, 22, 35, 49, 0, time.UTC)) request.SetEndDate(time.Date(2019, time.December, 12, 22, 35, 49, 0, time.UTC)) request.SetTransferId("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9") request.SetAccountId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr") request.SetTransferType(plaid.TRANSFEREVENTLISTTRANSFERTYPE_CREDIT) request.SetEventTypes([]plaid.TransferEventType{plaid.TRANSFEREVENTTYPE_PENDING, plaid.TRANSFEREVENTTYPE_POSTED}) request.SetCount(14) request.SetOffset(2) request.SetOriginationAccountId("8945fedc-e703-463d-86b1-dc0607b55460") response, _, err := client.PlaidApi.TransferEventList(ctx).TransferEventListRequest(*request).Execute() ``` #### Response fields  \[object\] integer Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers. Minimum: `0` string The datetime when this event occurred. This will be of the form `2006-01-02T15:04:05Z`. Format: `date-time` string The type of event that this transfer represents. Event types with prefix `sweep` represents events for Plaid Ledger sweeps. `pending`: A new transfer was created; it is in the pending state. `cancelled`: The transfer was cancelled by the client. `failed`: The transfer failed, no funds were moved. `posted`: The transfer has been successfully submitted to the payment network. `settled`: The transfer has been successfully completed by the payment network. `funds_available`: Funds from the transfer have been released from hold and applied to the ledger's available balance. (Only applicable to ACH debits.) `returned`: A posted transfer was returned. `swept`: The transfer was swept to / from the sweep account. `swept_settled`: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. `return_swept`: Due to the transfer being returned, funds were pulled from or pushed back to the sweep account. `sweep.pending`: A new ledger sweep was created; it is in the pending state. `sweep.posted`: The ledger sweep has been successfully submitted to the payment network. `sweep.settled`: The transaction has settled in the funding account. This means that funds withdrawn from Plaid Ledger balance have reached the funding account, or funds to be deposited into the Plaid Ledger Balance have been pulled, and the hold period has begun. `sweep.returned`: A posted ledger sweep was returned. `sweep.failed`: The ledger sweep failed, no funds were moved. `sweep.funds_available`: Funds from the ledger sweep have been released from hold and applied to the ledger's available balance. This is only applicable to debits. `refund.pending`: A new refund was created; it is in the pending state. `refund.cancelled`: The refund was cancelled. `refund.failed`: The refund failed, no funds were moved. `refund.posted`: The refund has been successfully submitted to the payment network. `refund.settled`: The refund transaction has settled in the Plaid linked account. `refund.returned`: A posted refund was returned. `refund.swept`: The refund was swept from the sweep account. `refund.return_swept`: Due to the refund being returned, funds were pushed back to the sweep account. Possible values: `pending`, `cancelled`, `failed`, `posted`, `settled`, `funds_available`, `returned`, `swept`, `swept_settled`, `return_swept`, `sweep.pending`, `sweep.posted`, `sweep.settled`, `sweep.returned`, `sweep.failed`, `sweep.funds_available`, `refund.pending`, `refund.cancelled`, `refund.failed`, `refund.posted`, `refund.settled`, `refund.returned`, `refund.swept`, `refund.return_swept` string The account ID associated with the transfer. This field is omitted for Plaid Ledger Sweep events. nullable, string The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string Plaid's unique identifier for a transfer. This field is an empty string for Plaid Ledger Sweep events. string The type of transfer. Valid values are `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. This field is omitted for Plaid Ledger Sweep events. Possible values: `debit`, `credit` string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). This field is omitted for Plaid Ledger Sweep events. nullable, object The failure reason if the event type for a transfer is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the transfer status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . string A human-readable description of the reason for the failure or reversal. nullable, string Plaid’s unique identifier for a sweep. nullable, string A signed amount of how much was `swept` or `return_swept` for this transfer (decimal string with two digits of precision e.g. "-5.50"). nullable, string Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer. nullable, string The Plaid client ID that is the originator of the transfer that this event applies to. Only present if the transfer was created on behalf of another client as a third-party sender (TPS). nullable, string The `id` returned by the /transfer/intent/create endpoint, for transfers created via Transfer UI. For transfers not created by Transfer UI, the value is `null`. This will currently only be populated for RfP transfers. nullable, string The fee amount deducted from the original transfer during a wire return, if applicable. boolean Whether there are more events to be pulled from the endpoint that have not already been returned string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "transfer_events": [ { "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "transfer_amount": "12.34", "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "transfer_type": "credit", "event_id": 1, "event_type": "posted", "failure_reason": null, "origination_account_id": "", "originator_client_id": "569ed2f36b3a3a021713abc1", "refund_id": null, "sweep_amount": null, "sweep_id": null, "timestamp": "2019-12-09T17:27:15Z" } ], "has_more": true, "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /transfer/event/sync  #### Sync transfer events  [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) allows you to request up to the next 500 transfer events that happened after a specific `event_id`. Use the [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) endpoint to guarantee you have seen all transfer events. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, integer The latest (largest) `event_id` fetched via the sync endpoint, or 0 initially. Minimum: `0` integer The maximum number of transfer events to return. Default: `100` Minimum: `1` Maximum: `500` ```bash curl -X POST https://sandbox.plaid.com/transfer/event/sync \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "after_id": 4, "count": 22 }' ``` ```python request = TransferEventSyncRequest( after_id=4, count=22 ) response = client.transfer_event_sync(request) events = response["transfer_events"] for event in events: # iterate through events ``` ```node const request: TransferEventSyncRequest = { after_id: 4, count: 22, }; try { const response = await plaidClient.transferEventSync(request); const events = response.data.transfer_events; for (const event of events) { // iterate through events } } catch (error) { // handle error } ``` ```java TransferEventSyncRequest request = new TransferEventSyncRequest() .afterId(4) .count(22); Response response = client() .transferEventSync(request) .execute(); List transferEvents = response.body().getTransferEvents(); for (TransferEvent e : transferEvents) { // iterate through events } ``` ```ruby request = Plaid::TransferEventSyncRequest.new( { after_id: 4, count: 22 } ) response = client.transfer_event_sync(request) response.transfer_events.each do |event| # iterate through events end ``` ```go request := plaid.NewTransferEventSyncRequest( 4, // after_id 22, //count ) response, _, err := client.PlaidApi.TransferEventSync(ctx).TransferEventSyncRequest(*request).Execute() ``` #### Response fields  \[object\] integer Plaid’s unique identifier for this event. IDs are sequential unsigned 64-bit integers. Minimum: `0` string The datetime when this event occurred. This will be of the form `2006-01-02T15:04:05Z`. Format: `date-time` string The type of event that this transfer represents. Event types with prefix `sweep` represents events for Plaid Ledger sweeps. `pending`: A new transfer was created; it is in the pending state. `cancelled`: The transfer was cancelled by the client. `failed`: The transfer failed, no funds were moved. `posted`: The transfer has been successfully submitted to the payment network. `settled`: The transfer has been successfully completed by the payment network. `funds_available`: Funds from the transfer have been released from hold and applied to the ledger's available balance. (Only applicable to ACH debits.) `returned`: A posted transfer was returned. `swept`: The transfer was swept to / from the sweep account. `swept_settled`: Credits are available to be withdrawn or debits have been deducted from the customer’s business checking account. `return_swept`: Due to the transfer being returned, funds were pulled from or pushed back to the sweep account. `sweep.pending`: A new ledger sweep was created; it is in the pending state. `sweep.posted`: The ledger sweep has been successfully submitted to the payment network. `sweep.settled`: The transaction has settled in the funding account. This means that funds withdrawn from Plaid Ledger balance have reached the funding account, or funds to be deposited into the Plaid Ledger Balance have been pulled, and the hold period has begun. `sweep.returned`: A posted ledger sweep was returned. `sweep.failed`: The ledger sweep failed, no funds were moved. `sweep.funds_available`: Funds from the ledger sweep have been released from hold and applied to the ledger's available balance. This is only applicable to debits. `refund.pending`: A new refund was created; it is in the pending state. `refund.cancelled`: The refund was cancelled. `refund.failed`: The refund failed, no funds were moved. `refund.posted`: The refund has been successfully submitted to the payment network. `refund.settled`: The refund transaction has settled in the Plaid linked account. `refund.returned`: A posted refund was returned. `refund.swept`: The refund was swept from the sweep account. `refund.return_swept`: Due to the refund being returned, funds were pushed back to the sweep account. Possible values: `pending`, `cancelled`, `failed`, `posted`, `settled`, `funds_available`, `returned`, `swept`, `swept_settled`, `return_swept`, `sweep.pending`, `sweep.posted`, `sweep.settled`, `sweep.returned`, `sweep.failed`, `sweep.funds_available`, `refund.pending`, `refund.cancelled`, `refund.failed`, `refund.posted`, `refund.settled`, `refund.returned`, `refund.swept`, `refund.return_swept` string The account ID associated with the transfer. This field is omitted for Plaid Ledger Sweep events. nullable, string The id of the associated funding account, available in the Plaid Dashboard. If present, this indicates which of your business checking accounts will be credited or debited. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string Plaid's unique identifier for a transfer. This field is an empty string for Plaid Ledger Sweep events. string The type of transfer. Valid values are `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. This field is omitted for Plaid Ledger Sweep events. Possible values: `debit`, `credit` string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). This field is omitted for Plaid Ledger Sweep events. nullable, object The failure reason if the event type for a transfer is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the transfer status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . string A human-readable description of the reason for the failure or reversal. nullable, string Plaid’s unique identifier for a sweep. nullable, string A signed amount of how much was `swept` or `return_swept` for this transfer (decimal string with two digits of precision e.g. "-5.50"). nullable, string Plaid’s unique identifier for a refund. A non-null value indicates the event is for the associated refund of the transfer. nullable, string The Plaid client ID that is the originator of the transfer that this event applies to. Only present if the transfer was created on behalf of another client as a third-party sender (TPS). nullable, string The `id` returned by the /transfer/intent/create endpoint, for transfers created via Transfer UI. For transfers not created by Transfer UI, the value is `null`. This will currently only be populated for RfP transfers. nullable, string The fee amount deducted from the original transfer during a wire return, if applicable. boolean Whether there are more events to be pulled from the endpoint that have not already been returned string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "transfer_events": [ { "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "transfer_amount": "12.34", "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "transfer_type": "credit", "event_id": 1, "event_type": "pending", "failure_reason": null, "origination_account_id": "", "originator_client_id": null, "refund_id": null, "sweep_amount": null, "sweep_id": null, "timestamp": "2019-12-09T17:27:15Z" } ], "has_more": true, "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /transfer/sweep/get  #### Retrieve a sweep  The [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) endpoint fetches a sweep corresponding to the given `sweep_id`. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid's unique identifier for the sweep (UUID) or a shortened form consisting of the first 8 characters of the identifier (8-digit hexadecimal string). ```node const request: TransferSweepGetRequest = { sweep_id: '8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee', }; try { const response = await plaidClient.transferSweepGet(request); const sweep = response.data.sweep; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/sweep/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "sweep_id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee" }' ``` ```ruby request = Plaid::TransferSweepGetRequest.new({ sweep_id: '8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee' }) response = client.transfer_sweep_get(request) sweep = response.sweep ``` ```java TransferSweepGetRequest request = new TransferSweepGetRequest() .sweepId("8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee"); Response response = client() .transferSweepGet(request) .execute(); Sweep sweep = response.body().getSweep(); ``` ```python request = TransferSweepGetRequest(sweep_id='8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee') response = client.transfer_sweep_get(request) sweep = response['sweep'] ``` ```go req := plaid.NewTransferSweepGetRequest("8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee") response, _, err := client.PlaidApi.TransferSweepGet(ctx).TransferSweepGetRequest(*req).Execute() if err != nil { plaidErr, _ := plaid.ToPlaidError(err) fmt.Println(plaidErr.ErrorMessage) } sweep := response.GetSweep() ``` #### Response fields  object Describes a sweep of funds to / from the sweep account. A sweep is associated with many sweep events (events of type `swept` or `return_swept`) which can be retrieved by invoking the `/transfer/event/list` endpoint with the corresponding `sweep_id`. `swept` events occur when the transfer amount is credited or debited from your sweep account, depending on the `type` of the transfer. `return_swept` events occur when a transfer is returned and Plaid undoes the credit or debit. The total sum of the `swept` and `return_swept` events is equal to the `amount` of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger. string Identifier of the sweep. string The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The datetime when the sweep occurred, in RFC 3339 format. Format: `date-time` string Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00") If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced. string The currency of the sweep, e.g. "USD". nullable, string The date when the sweep settled, in the YYYY-MM-DD format. Format: `date` nullable, string The expected date when funds from a ledger deposit will be made available and can be withdrawn from the associated ledger balance. Only applies to deposits. This will be of the form YYYY-MM-DD. Format: `date` nullable, string The status of a sweep transfer `"pending"` - The sweep is currently pending `"posted"` - The sweep has been posted `"settled"` - The sweep has settled. This is the terminal state of a successful credit sweep. `"returned"` - The sweep has been returned. This is the terminal state of a returned sweep. Returns of a sweep are extremely rare, since sweeps are money movement between your own bank account and your own Ledger. `"funds_available"` - Funds from the sweep have been released from hold and applied to the ledger's available balance. (Only applicable to deposits.) This is the terminal state of a successful deposit sweep. `"failed"` - The sweep has failed. This is the terminal state of a failed sweep. Possible values: `pending`, `posted`, `settled`, `funds_available`, `returned`, `failed`, `null` nullable, string The trigger of the sweep `"manual"` - The sweep is created manually by the customer `"incoming"` - The sweep is created by incoming funds flow (e.g. Incoming Wire) `"balance_threshold"` - The sweep is created by balance threshold setting `"automatic_aggregate"` - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance. Possible values: `manual`, `incoming`, `balance_threshold`, `automatic_aggregate` string The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement. nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. nullable, object The failure reason if the status for a sweep is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the sweep status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. nullable, string A human-readable description of the reason for the failure or reversal. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "sweep": { "id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "created": "2020-08-06T17:27:15Z", "amount": "12.34", "iso_currency_code": "USD", "settled": "2020-08-07", "status": "settled", "network_trace_id": "123456789012345" }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/sweep/list  #### List sweeps  The [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) endpoint fetches sweeps matching the given filters. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The start `created` datetime of sweeps to return (RFC 3339 format). Format: `date-time` string The end `created` datetime of sweeps to return (RFC 3339 format). Format: `date-time` integer The maximum number of sweeps to return. Minimum: `1` Maximum: `25` Default: `25` integer The number of sweeps to skip before returning results. Default: `0` Minimum: `0` string Filter sweeps to only those with the specified amount. string The status of a sweep transfer `"pending"` - The sweep is currently pending `"posted"` - The sweep has been posted `"settled"` - The sweep has settled. This is the terminal state of a successful credit sweep. `"returned"` - The sweep has been returned. This is the terminal state of a returned sweep. Returns of a sweep are extremely rare, since sweeps are money movement between your own bank account and your own Ledger. `"funds_available"` - Funds from the sweep have been released from hold and applied to the ledger's available balance. (Only applicable to deposits.) This is the terminal state of a successful deposit sweep. `"failed"` - The sweep has failed. This is the terminal state of a failed sweep. Possible values: `pending`, `posted`, `settled`, `funds_available`, `returned`, `failed`, `null` string Filter sweeps to only those with the specified originator client. string Filter sweeps to only those with the specified `funding_account_id`. string Filter sweeps to only those with the included `transfer_id`. string The trigger of the sweep `"manual"` - The sweep is created manually by the customer `"incoming"` - The sweep is created by incoming funds flow (e.g. Incoming Wire) `"balance_threshold"` - The sweep is created by balance threshold setting `"automatic_aggregate"` - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance. Possible values: `manual`, `incoming`, `balance_threshold`, `automatic_aggregate` ```node const request: TransferSweepListRequest = { start_date: '2019-12-06T22:35:49Z', end_date: '2019-12-12T22:35:49Z', count: 14, offset: 2, }; try { const response = await plaidClient.transferSweepList(request); const sweeps = response.data.sweeps; for (const sweep of sweeps) { // iterate through sweeps } } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/sweep/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "start_date": "2019-12-06T22:35:49Z", "end_date": "2019-12-12T22:35:49Z", "count": 14, "offset": 2 }' ``` ```ruby require 'time' request = Plaid::TransferSweepListRequest.new( { start_date: Time.parse("2019-12-06T22:35:49Z"), end_date: Time.parse("2019-12-12T22:35:49Z"), count: 14, offset: 2 } ) response = client.transfer_sweep_list(request) response.sweeps.each do |sweep| # iterate through sweeps end ``` ```java import java.time.OffsetDateTime; OffsetDateTime startDate = OffsetDateTime.parse("2019-12-06T22:35:49+00:00"); OffsetDateTime endDate = OffsetDateTime.parse("2019-12-12T22:35:49+00:00"); TransferSweepListRequest request = new TransferSweepListRequest() .startDate(startDate) .endDate(endDate) .count(14) .offset(2); Response response = client() .transferSweepList(request) .execute(); List sweeps = response.body().getSweeps(); for (Sweeps sweep : sweeps) { // iterate through sweeps } ``` ```python import datetime request = TransferSweepListRequest( start_date=datetime.datetime(2019, 12, 6, 22, 35, 49, tzinfo=datetime.timezone.utc), end_date=datetime.datetime(2019, 12, 12, 22, 35, 49, tzinfo=datetime.timezone.utc), count=14, offset=2 ) response = client.transfer_sweep_list(request) sweeps = response['sweeps'] for sweep in sweeps: # iterate through sweeps ``` ```go import ( "time" ) request := plaid.NewTransferSweepListRequest() request.SetStartDate(time.Date(2019, time.December, 6, 22, 35, 49, 0, time.UTC)) request.SetEndDate(time.Date(2019, time.December, 12, 22, 35, 49, 0, time.UTC)) request.SetCount(14) request.SetOffset(2) response, _, err := client.PlaidApi.TransferSweepList(ctx).TransferSweepListRequest(*request).Execute() if err != nil { plaidErr, _ := plaid.ToPlaidError(err) fmt.Println(plaidErr.ErrorMessage) } _ = response.GetSweeps() ``` #### Response fields  \[object\] string Identifier of the sweep. string The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The datetime when the sweep occurred, in RFC 3339 format. Format: `date-time` string Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00") If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced. string The currency of the sweep, e.g. "USD". nullable, string The date when the sweep settled, in the YYYY-MM-DD format. Format: `date` nullable, string The expected date when funds from a ledger deposit will be made available and can be withdrawn from the associated ledger balance. Only applies to deposits. This will be of the form YYYY-MM-DD. Format: `date` nullable, string The status of a sweep transfer `"pending"` - The sweep is currently pending `"posted"` - The sweep has been posted `"settled"` - The sweep has settled. This is the terminal state of a successful credit sweep. `"returned"` - The sweep has been returned. This is the terminal state of a returned sweep. Returns of a sweep are extremely rare, since sweeps are money movement between your own bank account and your own Ledger. `"funds_available"` - Funds from the sweep have been released from hold and applied to the ledger's available balance. (Only applicable to deposits.) This is the terminal state of a successful deposit sweep. `"failed"` - The sweep has failed. This is the terminal state of a failed sweep. Possible values: `pending`, `posted`, `settled`, `funds_available`, `returned`, `failed`, `null` nullable, string The trigger of the sweep `"manual"` - The sweep is created manually by the customer `"incoming"` - The sweep is created by incoming funds flow (e.g. Incoming Wire) `"balance_threshold"` - The sweep is created by balance threshold setting `"automatic_aggregate"` - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance. Possible values: `manual`, `incoming`, `balance_threshold`, `automatic_aggregate` string The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement. nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. nullable, object The failure reason if the status for a sweep is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the sweep status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. nullable, string A human-readable description of the reason for the failure or reversal. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "sweeps": [ { "id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "ledger_id": "563db5f8-4c95-4e17-8c3e-cb988fb9cf1a", "created": "2019-12-09T17:27:15Z", "amount": "-12.34", "iso_currency_code": "USD", "settled": "2019-12-10", "status": "settled", "originator_client_id": null } ], "request_id": "saKrIBuEB9qJZno" } ``` ### Webhooks  \=\*=\*=\*= #### TRANSFER\_EVENTS\_UPDATE  Fired when new transfer events are available. Receiving this webhook indicates you should fetch the new events from [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) . If multiple transfer events occur within a single minute, only one webhook will be fired, so a single webhook instance may correspond to multiple transfer events. #### Properties  string `TRANSFER` string `TRANSFER_EVENTS_UPDATE` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "TRANSFER", "webhook_code": "TRANSFER_EVENTS_UPDATE", "environment": "production" } ``` --- # API - Recurring Transfers | Plaid Docs Recurring transfers  ==================== #### API reference for recurring transfer endpoints and webhooks  #### Recurring transfers  For how-to guidance, see the [recurring transfers documentation](https://plaid.com/docs/transfer/recurring-transfers/index.html.md) . | Recurring Transfer endpoints | | | --- | --- | | [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) | Create a recurring transfer | | [/transfer/recurring/cancel](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcancel) | Cancel a recurring transfer | | [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) | Retrieve information about a recurring transfer | | [/transfer/recurring/list](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringlist) | Retrieve a list of recurring transfers | | Webhooks | | | --- | --- | | [RECURRING\_CANCELLED](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_new_transfer) | A recurring transfer has been cancelled by Plaid | | [RECURRING\_NEW\_TRANSFER](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_new_transfer) | A new transfer of a recurring transfer has been originated | | [RECURRING\_TRANSFER\_SKIPPED](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#recurring_transfer_skipped) | An instance of a scheduled recurring transfer could not be created | ### Endpoints  \=\*=\*=\*= #### /transfer/recurring/create  #### Create a recurring transfer  Use the [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) endpoint to initiate a new recurring transfer. This capability is not currently supported for Transfer UI or Transfer for Platforms (beta) customers. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The Plaid `access_token` for the account that will be debited or credited. required, string A random key provided by the client, per unique recurring transfer. Maximum of 50 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a recurring fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single recurring transfer is created. Max length: `50` required, string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. required, string The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `debit`, `credit` required, string Networks eligible for recurring transfers. Possible values: `ach`, `same-day-ach`, `rtp` string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` required, string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. boolean If the end user is initiating the specific transfer themselves via an interactive UI, this should be `true`; for automatic recurring payments where the end user is not actually initiating each individual transfer, it should be `false`. required, string The description of the recurring transfer. string Plaid’s unique identifier for a test clock. This field may only be used when using the `sandbox` environment. If provided, the created `recurring_transfer` is associated with the `test_clock`. New originations are automatically generated when the associated `test_clock` advances. For more details, see [Simulating recurring transfers](https://plaid.com/docs/transfer/sandbox/index.html.md#simulating-recurring-transfers) . required, object The schedule that the recurring transfer will be executed on. required, string The unit of the recurring interval. Possible values: `week`, `month` Min length: `1` required, integer The number of recurring `interval_units` between originations. The recurring interval (before holiday adjustment) is calculated by multiplying `interval_unit` and `interval_count`. For example, to schedule a recurring transfer which originates once every two weeks, set `interval_unit` = `week` and `interval_count` = 2. required, integer The day of the interval on which to schedule the transfer. If the `interval_unit` is `week`, `interval_execution_day` should be an integer from 1 (Monday) to 5 (Friday). If the `interval_unit` is `month`, `interval_execution_day` should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on. The transfer will be originated on the next available banking day if the designated day is a non banking day. required, string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). The recurring transfer will begin on the first `interval_execution_day` on or after the `start_date`. For `rtp` recurring transfers, `start_date` must be in the future. Otherwise, if the first `interval_execution_day` on or after the start date is also the same day that `/transfer/recurring/create` was called, the bank _may_ make the first payment on that day, but it is not guaranteed to do so. Format: `date` string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). The recurring transfer will end on the last `interval_execution_day` on or before the `end_date`. If the `interval_execution_day` between the start date and the end date (inclusive) is also the same day that `/transfer/recurring/create` was called, the bank _may_ make a payment on that day, but it is not guaranteed to do so. Format: `date` required, object The legal name and other information for the account holder. required, string The user's legal name. string The user's phone number. Phone number input may be validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. string The user's email address. object The address associated with the account holder. string The street number and name (i.e., "100 Market St."). string Ex. "San Francisco" string The state or province (e.g., "CA"). string The postal code (e.g., "94103"). string A two-letter country code (e.g., "US"). object Information about the device being used to initiate the authorization. required, string The IP address of the device being used to initiate the authorization. required, string The user agent of the device being used to initiate the authorization. ```node const request: TransferRecurringCreateRequest = { access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', type: 'credit', network: 'ach', amount: '12.34', ach_class: 'ppd', description: 'payment', idempotency_key: '12345', schedule: { start_date: '2022-10-01', end_date: '2023-10-01', interval_unit: 'week', interval_count: 1, interval_execution_day: 5 }, user: { legal_name: 'Anne Charleston', }, }; try { const response = await client.transferRecurringCreate(request); const recurringTransferId = response.data.recurring_transfer.recurring_transfer_id; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/recurring/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "type": "credit", "network": "ach", "amount": "12.34", "ach_class": "ppd", "idempotency_key": "12345", "description": "payment", "schedule": { "start_date": "2022-10-01", "end_date": "2023-10-01", "interval_unit": "week", "interval_count": 1, "interval_execution_day": 5 }, "user": { "legal_name": "Anne Charleston", "email_address": "acharleston@email.com", "phone_number": "510-555-0128", "address": { "street": "123 Main St.", "city": "San Francisco", "region": "CA", "postal_code": "94053", "country": "US" } }, }' ``` ```ruby request = Plaid::TransferRecurringCreateRequest.new( { access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', type: Plaid::TransferType::CREDIT, network: Plaid::TransferNetwork::ACH, amount: '12.34', ach_class: 'ppd', idempotency_key: '12345', description: 'payment', schedule: { start_date: '2022-10-01', end_date: '2023-10-01', interval_unit: 'week', interval_count: 1, interval_execution_day: 5 }, user: { legal_name: "Anne Charleston" } } ) response = client.transfer_recurring_create(request) recurring_transfer = response.recurring_transfer ``` ```java TransferUser user = new TransferUser().legalName("Anne Charleston"); TransferRecurringSchedule schedule = new TransferRecurringSchedule() .startDate("2022-10-01") .endDate("2023-10-01") .intervalUnit("week") .intervalCount(1) .intervalExecutionDay(5); TransferRecurringCreateRequest request = new TransferRecurringCreateRequest() .accessToken("access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175") .accountId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr") .type("credit") .network("ach") .amount("12.34") .user(user) .description("payment") .schedule(schedule) .idempotencyKey("12345") .achClass("ppd"); Response response = client() .transferRecurringCreate(request) .execute(); RecurringTransfer recurringTransfer = response.body().getRecurringTransfer(); ``` ```python request = TransferRecurringCreateRequest( access_token='access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id='3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', type=TransferType('credit'), network=TransferNetwork('ach'), amount='12.34', user=TransferUser(legal_name='Anne Charleston'), schedule=TransferRecurringSchedule(start_date='2022-10-01', interval_unit='week', interval_count=1, interval_execution_day=5, end_date='2023-10-01'), ach_class=ACHClass('ppd') ) response = client.transfer_recurring_create(request) recurring_transfer = response['recurring_transfer'] ``` ```go userPresent := true schedule := plaid.NewTransferRecurringSchedule("week", 1, 5, "2022-10-01") schedule.SetEndDate("2023-10-01") request := plaid.NewTransferRecurringCreateRequest( "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "12345", // idempotency_key "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", plaid.TRANSFERTYPE_CREDIT, plaid.TRANSFERNETWORK_ACH, *schedule, "12.34", "payment", *plaid.NewTransferUser("Anne Charleston"), ) request.SetUserPresent(userPresent) response, _, err := client.PlaidApi.TransferRecurringCreate(ctx).TransferRecurringCreateRequest(*request).Execute() ``` #### Response fields  nullable, object Represents a recurring transfer within the Transfers API. string Plaid’s unique identifier for a recurring transfer. string The datetime when this transfer was created. This will be of the form `2006-01-02T15:04:05Z` Format: `date-time` nullable, string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). The next transfer origination date after bank holiday adjustment. Format: `date` nullable, string Plaid’s unique identifier for a test clock. string The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `debit`, `credit` string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. string The status of the recurring transfer. `active`: The recurring transfer is currently active. `cancelled`: The recurring transfer was cancelled by the client or Plaid. `expired`: The recurring transfer has completed all originations according to its recurring schedule. Possible values: `active`, `cancelled`, `expired` string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` string Networks eligible for recurring transfers. Possible values: `ach`, `same-day-ach`, `rtp` string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. string The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. string The currency of the transfer amount, e.g. "USD" string The description of the recurring transfer. \[string\] The created transfer instances associated with this `recurring_transfer_id`. If the recurring transfer has been newly created, this array will be empty. object The legal name and other information for the account holder. string The user's legal name. nullable, string The user's phone number. nullable, string The user's email address. nullable, object The address associated with the account holder. nullable, string The street number and name (i.e., "100 Market St."). nullable, string Ex. "San Francisco" nullable, string The state or province (e.g., "CA"). nullable, string The postal code (e.g., "94103"). nullable, string A two-letter country code (e.g., "US"). object The schedule that the recurring transfer will be executed on. string The unit of the recurring interval. Possible values: `week`, `month` Min length: `1` integer The number of recurring `interval_units` between originations. The recurring interval (before holiday adjustment) is calculated by multiplying `interval_unit` and `interval_count`. For example, to schedule a recurring transfer which originates once every two weeks, set `interval_unit` = `week` and `interval_count` = 2. integer The day of the interval on which to schedule the transfer. If the `interval_unit` is `week`, `interval_execution_day` should be an integer from 1 (Monday) to 5 (Friday). If the `interval_unit` is `month`, `interval_execution_day` should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on. The transfer will be originated on the next available banking day if the designated day is a non banking day. string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). The recurring transfer will begin on the first `interval_execution_day` on or after the `start_date`. For `rtp` recurring transfers, `start_date` must be in the future. Otherwise, if the first `interval_execution_day` on or after the start date is also the same day that `/transfer/recurring/create` was called, the bank _may_ make the first payment on that day, but it is not guaranteed to do so. Format: `date` nullable, string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). The recurring transfer will end on the last `interval_execution_day` on or before the `end_date`. If the `interval_execution_day` between the start date and the end date (inclusive) is also the same day that `/transfer/recurring/create` was called, the bank _may_ make a payment on that day, but it is not guaranteed to do so. Format: `date` string A decision regarding the proposed transfer. `approved` – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The `decision_rationale` field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended. Refer to the `code` field in the `decision_rationale` object for details. `declined` – Plaid reviewed the proposed transfer and declined processing. Refer to the `code` field in the `decision_rationale` object for details. `user_action_required` – An action is required before Plaid can assess the transfer risk and make a decision. The most common scenario is to update authentication for an Item. To complete the required action, initialize Link by setting `transfer.authorization_id` in the request of `/link/token/create`. After Link flow is completed, you may re-attempt the authorization request. For `guarantee` requests, `approved` indicates the transfer is eligible for Plaid's guarantee, and `declined` indicates Plaid will not provide guarantee coverage for the transfer. `user_action_required` indicates you should follow the above guidance before re-attempting. Possible values: `approved`, `declined`, `user_action_required` nullable, object The rationale for Plaid's decision regarding a proposed transfer. It is always set for `declined` decisions, and may or may not be null for `approved` decisions. string A code representing the rationale for approving or declining the proposed transfer. If the `rationale_code` is `null`, the transfer passed the authorization check. Any non-`null` value for an `approved` transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an `approved` transfer are: `MANUALLY_VERIFIED_ITEM` – Item created via a manual entry flow (i.e. Same Day Micro-deposit, Instant Micro-deposit, or database-based verification), limited information available. `ITEM_LOGIN_REQUIRED` – Unable to collect the account information due to Item staleness. Can be resolved by using Link and setting [transfer.authorization\_id](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transfer-authorization-id) in the request to `/link/token/create`. `MIGRATED_ACCOUNT_ITEM` - Item created via `/transfer/migrate_account` endpoint, limited information available. `ERROR` – Unable to collect the account information due to an unspecified error. The following codes indicate that the authorization decision was `declined`: `NSF` – Transaction likely to result in a return due to insufficient funds. `RISK` - Transaction is high-risk. `TRANSFER_LIMIT_REACHED` - One or several transfer limits are reached, e.g. monthly transfer limit. Check the accompanying `description` field to understand which limit has been reached. Possible values: `NSF`, `RISK`, `TRANSFER_LIMIT_REACHED`, `MANUALLY_VERIFIED_ITEM`, `ITEM_LOGIN_REQUIRED`, `PAYMENT_PROFILE_LOGIN_REQUIRED`, `ERROR`, `MIGRATED_ACCOUNT_ITEM`, `null` string A human-readable description of the code associated with a transfer approval or transfer decline. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "recurring_transfer": { "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "created": "2022-07-05T12:48:37Z", "next_origination_date": "2022-10-28", "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c", "status": "active", "amount": "12.34", "description": "payment", "type": "debit", "ach_class": "ppd", "network": "ach", "origination_account_id": "", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "iso_currency_code": "USD", "transfer_ids": [], "user": { "legal_name": "Anne Charleston", "phone_number": "510-555-0128", "email_address": "acharleston@email.com", "address": { "street": "123 Main St.", "city": "San Francisco", "region": "CA", "postal_code": "94053", "country": "US" } }, "schedule": { "start_date": "2022-10-01", "end_date": "2023-10-01", "interval_unit": "week", "interval_count": 1, "interval_execution_day": 5 } }, "decision": "approved", "decision_rationale": null, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/recurring/cancel  #### Cancel a recurring transfer.  Use the [/transfer/recurring/cancel](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcancel) endpoint to cancel a recurring transfer. Scheduled transfer that hasn't been submitted to bank will be cancelled. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a recurring transfer. ```node const request: TransferRecurringCancelRequest = { recurring_transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', }; try { const response = await client.transferRecurringCancel(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/recurring/cancel \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9" }' ``` ```ruby request = Plaid::TransferRecurringCancelRequest.new( { recurring_transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9' } ) response = client.transfer_recurring_cancel(request) ``` ```java TransferRecurringCancelRequest request = new TransferRecurringCancelRequest() .recurringTransferId("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9"); Response response = client() .transferRecurringCancel(request) .execute(); ``` ```python request = TransferRecurringCancelRequest( recurring_transfer_id='460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9' ) response = client.transfer_recurring_cancel(request) ``` ```go request := plaid.NewTransferRecurringCancelRequest("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9") response, _, err := client.PlaidApi.TransferRecurringCancel(ctx).TransferRecurringCancelRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/recurring/get  #### Retrieve a recurring transfer  The [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) fetches information about the recurring transfer corresponding to the given `recurring_transfer_id`. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a recurring transfer. ```node const request: TransferRecurringGetRequest = { recurring_transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', }; try { const response = await client.transferRecurringGet(request); const recurringTransferId = response.data.recurring_transfer.recurring_transfer_id; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/recurring/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", }' ``` ```ruby request = Plaid::TransferRecurringGetRequest.new( { recurring_transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', } ) response = client.transfer_recurring_get(request) recurring_transfer = response.recurring_transfer ``` ```java TransferRecurringGetRequest request = new TransferRecurringGetRequest() .recurringTransferId("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9"); Response response = client() .transferRecurringGet(request) .execute(); RecurringTransfer recurringTransfer = response.body().getRecurringTransfer(); ``` ```python request = TransferRecurringGetRequest( recurring_transfer_id='460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', ) response = client.transfer_recurring_get(request) recurring_transfer = response['recurring_transfer'] ``` ```go request := plaid.NewTransferRecurringGetRequest( "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9" ) response, _, err := client.PlaidApi.TransferRecurringGet(ctx).TransferRecurringGetRequest(*request).Execute() ``` #### Response fields  object Represents a recurring transfer within the Transfers API. string Plaid’s unique identifier for a recurring transfer. string The datetime when this transfer was created. This will be of the form `2006-01-02T15:04:05Z` Format: `date-time` nullable, string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). The next transfer origination date after bank holiday adjustment. Format: `date` nullable, string Plaid’s unique identifier for a test clock. string The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `debit`, `credit` string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. string The status of the recurring transfer. `active`: The recurring transfer is currently active. `cancelled`: The recurring transfer was cancelled by the client or Plaid. `expired`: The recurring transfer has completed all originations according to its recurring schedule. Possible values: `active`, `cancelled`, `expired` string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` string Networks eligible for recurring transfers. Possible values: `ach`, `same-day-ach`, `rtp` string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. string The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. string The currency of the transfer amount, e.g. "USD" string The description of the recurring transfer. \[string\] The created transfer instances associated with this `recurring_transfer_id`. If the recurring transfer has been newly created, this array will be empty. object The legal name and other information for the account holder. string The user's legal name. nullable, string The user's phone number. nullable, string The user's email address. nullable, object The address associated with the account holder. nullable, string The street number and name (i.e., "100 Market St."). nullable, string Ex. "San Francisco" nullable, string The state or province (e.g., "CA"). nullable, string The postal code (e.g., "94103"). nullable, string A two-letter country code (e.g., "US"). object The schedule that the recurring transfer will be executed on. string The unit of the recurring interval. Possible values: `week`, `month` Min length: `1` integer The number of recurring `interval_units` between originations. The recurring interval (before holiday adjustment) is calculated by multiplying `interval_unit` and `interval_count`. For example, to schedule a recurring transfer which originates once every two weeks, set `interval_unit` = `week` and `interval_count` = 2. integer The day of the interval on which to schedule the transfer. If the `interval_unit` is `week`, `interval_execution_day` should be an integer from 1 (Monday) to 5 (Friday). If the `interval_unit` is `month`, `interval_execution_day` should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on. The transfer will be originated on the next available banking day if the designated day is a non banking day. string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). The recurring transfer will begin on the first `interval_execution_day` on or after the `start_date`. For `rtp` recurring transfers, `start_date` must be in the future. Otherwise, if the first `interval_execution_day` on or after the start date is also the same day that `/transfer/recurring/create` was called, the bank _may_ make the first payment on that day, but it is not guaranteed to do so. Format: `date` nullable, string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). The recurring transfer will end on the last `interval_execution_day` on or before the `end_date`. If the `interval_execution_day` between the start date and the end date (inclusive) is also the same day that `/transfer/recurring/create` was called, the bank _may_ make a payment on that day, but it is not guaranteed to do so. Format: `date` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "recurring_transfer": { "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "created": "2022-07-05T12:48:37Z", "next_origination_date": "2022-10-28", "test_clock_id": null, "status": "active", "amount": "12.34", "description": "payment", "type": "debit", "ach_class": "ppd", "network": "ach", "origination_account_id": "", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "iso_currency_code": "USD", "transfer_ids": [ "271ef220-dbf8-caeb-a7dc-a2b3e8a80963", "c8dbaf75-2abb-e2dc-4171-12448e13b848" ], "user": { "legal_name": "Anne Charleston", "phone_number": "510-555-0128", "email_address": "acharleston@email.com", "address": { "street": "123 Main St.", "city": "San Francisco", "region": "CA", "postal_code": "94053", "country": "US" } }, "schedule": { "start_date": "2022-10-01", "end_date": "2023-10-01", "interval_unit": "week", "interval_count": 1, "interval_execution_day": 5 } }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/recurring/list  #### List recurring transfers  Use the [/transfer/recurring/list](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringlist) endpoint to see a list of all your recurring transfers and their statuses. Results are paginated; use the `count` and `offset` query parameters to retrieve the desired recurring transfers. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The start `created` datetime of recurring transfers to list. This should be in RFC 3339 format (i.e. `2019-12-06T22:35:49Z`) Format: `date-time` string The end `created` datetime of recurring transfers to list. This should be in RFC 3339 format (i.e. `2019-12-06T22:35:49Z`) Format: `date-time` integer The maximum number of recurring transfers to return. Minimum: `1` Maximum: `25` Default: `25` integer The number of recurring transfers to skip before returning results. Default: `0` Minimum: `0` string Filter recurring transfers to only those with the specified `funding_account_id`. ```node const request: TransferRecurringListRequest = { start_time: '2022-09-29T20:35:49Z', end_time: '2022-10-29T20:35:49Z', count: 1, }; try { const response = await client.transferRecurringList(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/recurring/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "start_time": "2022-09-29T20:35:49Z", "end_time": "2022-10-29T20:35:49Z", "count": 1 }' ``` ```ruby request = Plaid::TransferRecurringListRequest.new( { start_time: '2022-09-29T20:35:49Z', end_time: '2022-10-29T20:35:49Z', count: 1 } ) response = client.transfer_recurring_list(request) recurring_transfers = response.recurring_transfers ``` ```java TransferRecurringListRequest request = new TransferRecurringListRequest() .startTime("2022-09-29T20:35:49Z") .endTime("2022-10-29T20:35:49Z") .count(1); Response response = client() .transferRecurringList(request) .execute(); List recurringTransfers = response.body().getRecurringTransfers(); ``` ```python request = TransferRecurringListRequest( start_time='2022-09-29T20:35:49Z', end_time='2022-10-29T20:35:49Z', count=1 ) response = client.transfer_recurring_list(request) recurring_transfers = response['recurring_transfers'] ``` ```go request := plaid.NewTransferRecurringListRequest() request.SetStartTime("2022-09-29T20:35:49Z") request.SetEndTime("2022-10-29T20:35:49Z") request.SetCount(1) response, _, err := client.PlaidApi.TransferRecurringList(ctx).TransferRecurringListRequest(*request).Execute() ``` #### Response fields  \[object\] string Plaid’s unique identifier for a recurring transfer. string The datetime when this transfer was created. This will be of the form `2006-01-02T15:04:05Z` Format: `date-time` nullable, string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). The next transfer origination date after bank holiday adjustment. Format: `date` nullable, string Plaid’s unique identifier for a test clock. string The type of transfer. This will be either `debit` or `credit`. A `debit` indicates a transfer of money into the origination account; a `credit` indicates a transfer of money out of the origination account. Possible values: `debit`, `credit` string The amount of the transfer (decimal string with two digits of precision e.g. "10.00"). When calling `/transfer/authorization/create`, specify the maximum amount to authorize. When calling `/transfer/create`, specify the exact amount of the transfer, up to a maximum of the amount authorized. If this field is left blank when calling `/transfer/create`, the maximum amount authorized in the `authorization_id` will be sent. string The status of the recurring transfer. `active`: The recurring transfer is currently active. `cancelled`: The recurring transfer was cancelled by the client or Plaid. `expired`: The recurring transfer has completed all originations according to its recurring schedule. Possible values: `active`, `cancelled`, `expired` string Specifies the use case of the transfer. Required for transfers on an ACH network. For more details, see [ACH SEC codes](https://plaid.com/docs/transfer/creating-transfers/index.html.md#ach-sec-codes) . Codes supported for credits: `ccd`, `ppd` Codes supported for debits: `ccd`, `tel`, `web` `"ccd"` - Corporate Credit or Debit - fund transfer between two corporate bank accounts `"ppd"` - Prearranged Payment or Deposit - The transfer is part of a pre-existing relationship with a consumer. Authorization was obtained in writing either in person or via an electronic document signing, e.g. Docusign, by the consumer. Can be used for credits or debits. `"web"` - Internet-Initiated Entry. The transfer debits a consumer’s bank account. Authorization from the consumer is obtained over the Internet (e.g. a web or mobile application). Can be used for single debits or recurring debits. `"tel"` - Telephone-Initiated Entry. The transfer debits a consumer. Debit authorization has been received orally over the telephone via a recorded call. Possible values: `ccd`, `ppd`, `tel`, `web` string Networks eligible for recurring transfers. Possible values: `ach`, `same-day-ach`, `rtp` string The Plaid `account_id` corresponding to the end-user account that will be debited or credited. string The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited. string The currency of the transfer amount, e.g. "USD" string The description of the recurring transfer. \[string\] The created transfer instances associated with this `recurring_transfer_id`. If the recurring transfer has been newly created, this array will be empty. object The legal name and other information for the account holder. string The user's legal name. nullable, string The user's phone number. nullable, string The user's email address. nullable, object The address associated with the account holder. nullable, string The street number and name (i.e., "100 Market St."). nullable, string Ex. "San Francisco" nullable, string The state or province (e.g., "CA"). nullable, string The postal code (e.g., "94103"). nullable, string A two-letter country code (e.g., "US"). object The schedule that the recurring transfer will be executed on. string The unit of the recurring interval. Possible values: `week`, `month` Min length: `1` integer The number of recurring `interval_units` between originations. The recurring interval (before holiday adjustment) is calculated by multiplying `interval_unit` and `interval_count`. For example, to schedule a recurring transfer which originates once every two weeks, set `interval_unit` = `week` and `interval_count` = 2. integer The day of the interval on which to schedule the transfer. If the `interval_unit` is `week`, `interval_execution_day` should be an integer from 1 (Monday) to 5 (Friday). If the `interval_unit` is `month`, `interval_execution_day` should be an integer indicating which day of the month to make the transfer on. Integers from 1 to 28 can be used to make a transfer on that day of the month. Negative integers from -1 to -5 can be used to make a transfer relative to the end of the month. To make a transfer on the last day of the month, use -1; to make the transfer on the second-to-last day, use -2, and so on. The transfer will be originated on the next available banking day if the designated day is a non banking day. string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). The recurring transfer will begin on the first `interval_execution_day` on or after the `start_date`. For `rtp` recurring transfers, `start_date` must be in the future. Otherwise, if the first `interval_execution_day` on or after the start date is also the same day that `/transfer/recurring/create` was called, the bank _may_ make the first payment on that day, but it is not guaranteed to do so. Format: `date` nullable, string A date in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DD). The recurring transfer will end on the last `interval_execution_day` on or before the `end_date`. If the `interval_execution_day` between the start date and the end date (inclusive) is also the same day that `/transfer/recurring/create` was called, the bank _may_ make a payment on that day, but it is not guaranteed to do so. Format: `date` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "recurring_transfers": [ { "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "created": "2022-07-05T12:48:37Z", "next_origination_date": "2022-10-28", "test_clock_id": null, "status": "active", "amount": "12.34", "description": "payment", "type": "debit", "ach_class": "ppd", "network": "ach", "origination_account_id": "", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460", "iso_currency_code": "USD", "transfer_ids": [ "4242fc8d-3ec6-fb38-fa0c-a8e37d03cd57" ], "user": { "legal_name": "Anne Charleston", "phone_number": "510-555-0128", "email_address": "acharleston@email.com", "address": { "street": "123 Main St.", "city": "San Francisco", "region": "CA", "postal_code": "94053", "country": "US" } }, "schedule": { "start_date": "2022-10-01", "end_date": "2023-10-01", "interval_unit": "week", "interval_count": 1, "interval_execution_day": 5 } } ], "request_id": "saKrIBuEB9qJZno" } ``` ### Webhooks  \=\*=\*=\*= #### RECURRING\_NEW\_TRANSFER  Fired when a new transfer of a recurring transfer is originated. #### Properties  string `TRANSFER` string `RECURRING_NEW_TRANSFER` string Plaid’s unique identifier for a recurring transfer. string Plaid’s unique identifier for a transfer. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "TRANSFER", "webhook_code": "RECURRING_NEW_TRANSFER", "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "transfer_id": "271ef220-dbf8-caeb-a7dc-a2b3e8a80963", "environment": "production" } ``` \=\*=\*=\*= #### RECURRING\_TRANSFER\_SKIPPED  Fired when Plaid is unable to originate a new ACH transaction of the recurring transfer on the planned date. #### Properties  string `TRANSFER` string `RECURRING_TRANSFER_SKIPPED` string Plaid’s unique identifier for a recurring transfer. string A decision regarding the proposed transfer. `approved` – The proposed transfer has received the end user's consent and has been approved for processing by Plaid. The `decision_rationale` field is set if Plaid was unable to fetch the account information. You may proceed with the transfer, but further review is recommended. Refer to the `code` field in the `decision_rationale` object for details. `declined` – Plaid reviewed the proposed transfer and declined processing. Refer to the `code` field in the `decision_rationale` object for details. `user_action_required` – An action is required before Plaid can assess the transfer risk and make a decision. The most common scenario is to update authentication for an Item. To complete the required action, initialize Link by setting `transfer.authorization_id` in the request of `/link/token/create`. After Link flow is completed, you may re-attempt the authorization request. For `guarantee` requests, `approved` indicates the transfer is eligible for Plaid's guarantee, and `declined` indicates Plaid will not provide guarantee coverage for the transfer. `user_action_required` indicates you should follow the above guidance before re-attempting. Possible values: `approved`, `declined`, `user_action_required` string A code representing the rationale for approving or declining the proposed transfer. If the `rationale_code` is `null`, the transfer passed the authorization check. Any non-`null` value for an `approved` transfer indicates that the the authorization check could not be run and that you should perform your own risk assessment on the transfer. The code will indicate why the check could not be run. Possible values for an `approved` transfer are: `MANUALLY_VERIFIED_ITEM` – Item created via a manual entry flow (i.e. Same Day Micro-deposit, Instant Micro-deposit, or database-based verification), limited information available. `ITEM_LOGIN_REQUIRED` – Unable to collect the account information due to Item staleness. Can be resolved by using Link and setting [transfer.authorization\_id](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-transfer-authorization-id) in the request to `/link/token/create`. `MIGRATED_ACCOUNT_ITEM` - Item created via `/transfer/migrate_account` endpoint, limited information available. `ERROR` – Unable to collect the account information due to an unspecified error. The following codes indicate that the authorization decision was `declined`: `NSF` – Transaction likely to result in a return due to insufficient funds. `RISK` - Transaction is high-risk. `TRANSFER_LIMIT_REACHED` - One or several transfer limits are reached, e.g. monthly transfer limit. Check the accompanying `description` field to understand which limit has been reached. Possible values: `NSF`, `RISK`, `TRANSFER_LIMIT_REACHED`, `MANUALLY_VERIFIED_ITEM`, `ITEM_LOGIN_REQUIRED`, `PAYMENT_PROFILE_LOGIN_REQUIRED`, `ERROR`, `MIGRATED_ACCOUNT_ITEM`, `null` string The planned date on which Plaid is unable to originate a new ACH transaction of the recurring transfer. This will be of the form YYYY-MM-DD. Format: `date` string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "TRANSFER", "webhook_code": "RECURRING_TRANSFER_SKIPPED", "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "authorization_decision": "declined", "authorization_decision_rationale_code": "NSF", "skipped_origination_date": "2022-11-30", "environment": "production" } ``` \=\*=\*=\*= #### RECURRING\_CANCELLED  Fired when a recurring transfer is cancelled by Plaid. #### Properties  string `TRANSFER` string `RECURRING_CANCELLED` string Plaid’s unique identifier for a recurring transfer. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "TRANSFER", "webhook_code": "RECURRING_CANCELLED", "recurring_transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "environment": "production" } ``` --- # API - Refunds | Plaid Docs Transfer refunds  ================= #### API reference for refunding transfers  For how-to guidance, see the [transfer refunds documentation](https://plaid.com/docs/transfer/refunds/index.html.md) . | Refunds | | | --- | --- | | [/transfer/refund/create](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcreate) | Create a refund for a transfer | | [/transfer/refund/cancel](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcancel) | Cancel a refund | | [/transfer/refund/get](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundget) | Retrieve information about a refund | \=\*=\*=\*= #### /transfer/refund/create  #### Create a refund  Use the [/transfer/refund/create](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcreate) endpoint to create a refund for a transfer. A transfer can be refunded if the transfer was initiated in the past 180 days. Refunds come out of the available balance of the ledger used for the original debit transfer. If there are not enough funds in the available balance to cover the refund amount, the refund will be rejected. You can create a refund at any time. Plaid does not impose any hold time on refunds. A refund can still be issued even if the Item's `access_token` is no longer valid (e.g. if the user revoked OAuth consent or the Item was deleted via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) ), as long as the account and routing number pair used to make the original transaction is still valid. A refund cannot be issued if the Item has an [invalidated TAN](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) , which can occur at Chase or PNC. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the transfer to refund. required, string The amount of the refund (decimal string with two digits of precision e.g. "10.00"). required, string A random key provided by the client, per unique refund. Maximum of 50 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a refund fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single refund is created. Max length: `50` ```node const request: TransferRefundCreateRequest = { transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', amount: '12.34', idempotency_key: 'VEK2ea3X6LKywsc8J6pg', }; try { const response = await client.transferRefundCreate(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/refund/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "amount": "12.34", "idempotency_key": "VEK2ea3X6LKywsc8J6pg" }' ``` ```ruby request = Plaid::TransferRefundCreateRequest.new( { transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', amount: '12.34', idempotency_key: 'VEK2ea3X6LKywsc8J6pg', } ) response = client.transfer_refund_create(request) ``` ```java TransferRefundCreateRequest request = new TransferRefundCreateRequest() .transferId("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9") .amount("12.34") .idempotencyKey("VEK2ea3X6LKywsc8J6pg"); Response response = client() .transferRefundCreate(request) .execute(); ``` ```python request = TransferRefundCreateRequest( transfer_id='460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', amount='12.34', idempotency_key='VEK2ea3X6LKywsc8J6pg', ) response = client.transfer_refund_create(request) ``` ```go request := plaid.NewTransferRefundCreateRequest( "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "12.34", "VEK2ea3X6LKywsc8J6pg", ) response, _, err := client.PlaidApi.TransferRefundCreate(ctx).TransferRefundCreateRequest(*request).Execute() ``` #### Response fields  object Represents a refund within the Transfers API. string Plaid’s unique identifier for a refund. string The ID of the transfer to refund. string The amount of the refund (decimal string with two digits of precision e.g. "10.00"). string The status of the refund. `pending`: A new refund was created; it is in the pending state. `posted`: The refund has been successfully submitted to the payment network. `settled`: Credits have been refunded to the Plaid linked account. `cancelled`: The refund was cancelled by the client. `failed`: The refund has failed. `returned`: The refund was returned. Possible values: `pending`, `posted`, `cancelled`, `failed`, `settled`, `returned` nullable, object The failure reason if the event type for a refund is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the refund status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the refund status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . This field is deprecated in favor of the more versatile `failure_code`, which encompasses non-ACH failure codes as well. string A human-readable description of the reason for the failure or reversal. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The datetime when this refund was created. This will be of the form `2006-01-02T15:04:05Z` Format: `date-time` nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "refund": { "id": "667af684-9ee1-4f5f-862a-633ec4c545cc", "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "amount": "12.34", "status": "pending", "created": "2020-08-06T17:27:15Z", "failure_reason": null, "network_trace_id": null }, "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/refund/cancel  #### Cancel a refund  Use the [/transfer/refund/cancel](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcancel) endpoint to cancel a refund. A refund is eligible for cancellation if it has not yet been submitted to the payment network. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a refund. ```node const request: TransferRefundCancelRequest = { refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', }; try { const response = await client.transferRefundCancel(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/refund/cancel \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "refund_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", }' ``` ```ruby request = Plaid::TransferRefundCancelRequest.new( { refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', } ) response = client.transfer_refund_cancel(request) ``` ```java TransferRefundCancelRequest request = new TransferRefundCancelRequest() .refundId("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9"); Response response = client() .transferRefundCancel(request) .execute(); ``` ```python request = TransferRefundCancelRequest( refund_id='460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', ) response = client.transfer_refund_cancel(request) ``` ```go request := plaid.NewTransferRefundCancelRequest( "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", ) response, _, err := client.PlaidApi.TransferRefundCancel(ctx).TransferRefundCancelRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "saKrIBuEB9qJZno" } ``` \=\*=\*=\*= #### /transfer/refund/get  #### Retrieve a refund  The [/transfer/refund/get](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundget) endpoint fetches information about the refund corresponding to the given `refund_id`. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a refund. ```node const request: TransferRefundGetRequest = { refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', }; try { const response = await client.transferRefundGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/transfer/refund/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "refund_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", }' ``` ```ruby request = Plaid::TransferRefundGetRequest.new( { refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', } ) response = client.transfer_refund_get(request) ``` ```java TransferRefundGetRequest request = new TransferRefundGetRequest() .refundId("460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9"); Response response = client() .transferRefundGet(request) .execute(); ``` ```python request = TransferRefundGetRequest( refund_id='460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9', ) response = client.transfer_refund_get(request) ``` ```go request := plaid.NewTransferRefundGetRequest( "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", ) response, _, err := client.PlaidApi.TransferRefundGet(ctx).TransferRefundGetRequest(*request).Execute() ``` #### Response fields  object Represents a refund within the Transfers API. string Plaid’s unique identifier for a refund. string The ID of the transfer to refund. string The amount of the refund (decimal string with two digits of precision e.g. "10.00"). string The status of the refund. `pending`: A new refund was created; it is in the pending state. `posted`: The refund has been successfully submitted to the payment network. `settled`: Credits have been refunded to the Plaid linked account. `cancelled`: The refund was cancelled by the client. `failed`: The refund has failed. `returned`: The refund was returned. Possible values: `pending`, `posted`, `cancelled`, `failed`, `settled`, `returned` nullable, object The failure reason if the event type for a refund is `"failed"` or `"returned"`. Null value otherwise. nullable, string The failure code, e.g. `R01`. A failure code will be provided if and only if the refund status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, nullable, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the refund status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . This field is deprecated in favor of the more versatile `failure_code`, which encompasses non-ACH failure codes as well. string A human-readable description of the reason for the failure or reversal. nullable, string Plaid’s unique identifier for a Plaid Ledger Balance. string The datetime when this refund was created. This will be of the form `2006-01-02T15:04:05Z` Format: `date-time` nullable, string The trace identifier for the transfer based on its network. This will only be set after the transfer has posted. For `ach` or `same-day-ach` transfers, this is the ACH trace number. For `rtp` transfers, this is the Transaction Identification number. For `wire` transfers, this is the IMAD (Input Message Accountability Data) number. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "refund": { "id": "667af684-9ee1-4f5f-862a-633ec4c545cc", "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9", "amount": "12.34", "status": "pending", "created": "2020-08-06T17:27:15Z", "failure_reason": null, "network_trace_id": null }, "request_id": "saKrIBuEB9qJZno" } ``` --- # API - Virtual Accounts | Plaid Docs Virtual Accounts (UK and Europe)  ================================= #### API reference for Virtual Accounts endpoints and webhooks  Manage the entire lifecycle of a payment. For how-to guidance, see the [Virtual Accounts documentation](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) . | Endpoints | | | --- | --- | | [/wallet/create](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletcreate) | Create a virtual account | | [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) | Fetch a virtual account | | [/wallet/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletlist) | List all virtual accounts | | [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) | Execute a transaction | | [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) | Fetch a transaction | | [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) | List all transactions | | See also | | | --- | --- | | [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) | Refund a payment from a virtual account | | Webhooks | | | --- | --- | | [WALLET\_TRANSACTION\_STATUS\_UPDATE](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) | The status of a transaction has changed | ### Endpoints  \=\*=\*=\*= #### /wallet/create  #### Create an e-wallet  Create an e-wallet. The response is the newly created e-wallet object. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string An ISO-4217 currency code, used with e-wallets and transactions. Possible values: `GBP`, `EUR` Min length: `3` Max length: `3` ```go request := plaid.NewWalletCreateRequest(isoCurrencyCode) response, _, err := client.PlaidApi.WalletCreate(ctx).WalletCreateRequest(*request).Execute() walletID := response.GetWalletId() balance := response.GetBalance() numbers := response.GetNumbers() recipientID := response.GetRecipientId() ``` ```java WalletCreateRequest request = new WalletCreateRequest() .isoCurrencyCode(isoCurrencyCode); Response response = client() .walletCreate(request) .execute(); String walletId = response.body().getWalletId(); WalletBalance balance = response.body().getBalance(); WalletNumbers numbers = response.body().getNumbers(); String recipientId = response.body().getRecipientId(); ``` ```ruby request = Plaid::WalletCreateRequest.new({ iso_currency_code: iso_currency_code }) response = client.wallet_create(request) wallet_id = response.wallet_id balance = response.balance numbers = response.numbers recipient_id = response.recipient_id ``` ```node const request: WalletCreateRequest = { iso_currency_code: isoCurrencyCode, }; try { const response = await plaidClient.walletCreate(request); const walletID = response.data.wallet_id; const balance = response.data.balance; const numbers = response.data.numbers; const recipientID = response.data.recipient_id; } catch (error) { // handle error } ``` ```bash curl -X POST https://production.plaid.com/wallet/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "iso_currency_code": "${ISO_CURRENCY_CODE}" }' ``` ```python request = WalletCreateRequest(iso_currency_code=iso_currency_code) response = client.wallet_create(request) wallet_id = response['wallet_id'] balance = response['balance'] numbers = response['numbers'] recipient_id = response['recipient_id'] ``` #### Response fields  string A unique ID identifying the e-wallet object An object representing the e-wallet balance string The ISO-4217 currency code of the balance number The total amount of funds in the account Format: `double` number The total amount of funds in the account after subtracting pending debit transaction amounts Format: `double` object An object representing the e-wallet account numbers nullable, object An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` nullable, object Account numbers using the International Bank Account Number and BIC/SWIFT code format. string International Bank Account Number (IBAN). Min length: `15` Max length: `34` string The Business Identifier Code, also known as SWIFT code, for this bank account. Min length: `8` Max length: `11` string The ID of the recipient that corresponds to the e-wallet account numbers string The status of the wallet. `UNKNOWN`: The wallet status is unknown. `ACTIVE`: The wallet is active and ready to send money to and receive money from. `CLOSED`: The wallet is closed. Any transactions made to or from this wallet will error. Possible values: `UNKNOWN`, `ACTIVE`, `CLOSED` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88", "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6", "balance": { "iso_currency_code": "GBP", "current": 123.12, "available": 100.96 }, "request_id": "4zlKapIkTm8p5KM", "numbers": { "bacs": { "account": "12345678", "sort_code": "123456" } }, "status": "ACTIVE" } ``` \=\*=\*=\*= #### /wallet/get  #### Fetch an e-wallet  Fetch an e-wallet. The response includes the current balance. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the e-wallet Min length: `1` ```go request := plaid.NewWalletGetRequest(walletID) response, _, err := client.PlaidApi.WalletGet(ctx).WalletGetRequest(*request).Execute() walletID := response.GetWalletId() balance := response.GetBalance() numbers := response.GetNumbers() recipientID := response.GetRecipientId() ``` ```java WalletGetRequest request = new WalletGetRequest() .walletId(walletId); Response response = client() .walletGet(request) .execute(); String walletId = response.body().getWalletId(); WalletBalance balance = response.body().getBalance(); WalletNumbers numbers = response.body().getNumbers(); String recipientID = response.body().getRecipientId(); ``` ```ruby request = Plaid::WalletGetRequest.new({ wallet_id: wallet_id }) response = client.wallet_get(request) wallet_id = response.wallet_id balance = response.balance numbers = response.numbers recipient_id = response.recipient_id ``` ```node const request: WalletGetRequest = { wallet_id: walletID, }; try { const response = await plaidClient.walletGet(request); const walletID = response.data.wallet_id; const balance = response.data.balance; const numbers = response.data.numbers; const recipientID = response.data.recipient_id; } catch (error) { // handle error } ``` ```bash curl -X POST https://production.plaid.com/wallet/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "wallet_id": "${WALLET_ID}" }' ``` ```python request = WalletGetRequest(wallet_id=wallet_id) response = client.wallet_get(request) wallet_id = response['wallet_id'] balance = response['balance'] numbers = response['numbers'] recipient_id = response['recipient_id'] ``` #### Response fields  string A unique ID identifying the e-wallet object An object representing the e-wallet balance string The ISO-4217 currency code of the balance number The total amount of funds in the account Format: `double` number The total amount of funds in the account after subtracting pending debit transaction amounts Format: `double` object An object representing the e-wallet account numbers nullable, object An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` nullable, object Account numbers using the International Bank Account Number and BIC/SWIFT code format. string International Bank Account Number (IBAN). Min length: `15` Max length: `34` string The Business Identifier Code, also known as SWIFT code, for this bank account. Min length: `8` Max length: `11` string The ID of the recipient that corresponds to the e-wallet account numbers string The status of the wallet. `UNKNOWN`: The wallet status is unknown. `ACTIVE`: The wallet is active and ready to send money to and receive money from. `CLOSED`: The wallet is closed. Any transactions made to or from this wallet will error. Possible values: `UNKNOWN`, `ACTIVE`, `CLOSED` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88", "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6", "balance": { "iso_currency_code": "GBP", "current": 123.12, "available": 100.96 }, "request_id": "4zlKapIkTm8p5KM", "numbers": { "bacs": { "account": "12345678", "sort_code": "123456" }, "international": { "iban": "GB33BUKB20201555555555", "bic": "BUKBGB22" } }, "status": "ACTIVE" } ``` \=\*=\*=\*= #### /wallet/list  #### Fetch a list of e-wallets  This endpoint lists all e-wallets in descending order of creation. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string An ISO-4217 currency code, used with e-wallets and transactions. Possible values: `GBP`, `EUR` Min length: `3` Max length: `3` string A base64 value representing the latest e-wallet that has already been requested. Set this to `next_cursor` received from the previous `/wallet/list` request. If provided, the response will only contain e-wallets created before that e-wallet. If omitted, the response will contain e-wallets starting from the most recent, and in descending order. Max length: `1024` integer The number of e-wallets to fetch Minimum: `1` Maximum: `20` Default: `10` ```go request := plaid.NewWalletListRequest() request.SetIsoCurrencyCode(plaid.WALLETISOCURRENCYCODE_GBP) request.SetCount(10) response, _, err := client.PlaidApi.WalletList(ctx).WalletListRequest(*request).Execute() wallets := response.GetWallets() nextCursor := response.GetNextCursor() ``` ```java WalletListRequest request = new WalletListRequest() .isoCurrencyCode(WalletISOCurrencyCode.GBP) .count(10); Response response = client() .walletList(request) .execute(); List wallets = response.body().getWallets(); String nextCursor = response.body().getNextCursor(); ``` ```ruby request = Plaid::WalletListRequest.new( { iso_currency_code: 'GBP', count: 10 } ) response = client.wallet_list(request) wallets = response.wallets next_cursor = response.next_cursor ``` ```node const request: WalletListRequest = { iso_currency_code: 'GBP', count: 10, }; try { const response = await plaidClient.walletList(request); const wallets = response.data.wallets; const nextCursor = response.data.next_cursor; } catch (error) { // handle error } ``` ```bash curl -X POST https://production.plaid.com/wallet/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "iso_currency_code": "GBP", "count": 10 }' ``` ```python request = WalletListRequest( iso_currency_code='GBP', count=10 ) response = client.wallet_list(request) wallets = response['wallets'] next_cursor = response['next_cursor'] ``` #### Response fields  \[object\] An array of e-wallets string A unique ID identifying the e-wallet object An object representing the e-wallet balance string The ISO-4217 currency code of the balance number The total amount of funds in the account Format: `double` number The total amount of funds in the account after subtracting pending debit transaction amounts Format: `double` object An object representing the e-wallet account numbers nullable, object An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required. string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` nullable, object Account numbers using the International Bank Account Number and BIC/SWIFT code format. string International Bank Account Number (IBAN). Min length: `15` Max length: `34` string The Business Identifier Code, also known as SWIFT code, for this bank account. Min length: `8` Max length: `11` string The ID of the recipient that corresponds to the e-wallet account numbers string The status of the wallet. `UNKNOWN`: The wallet status is unknown. `ACTIVE`: The wallet is active and ready to send money to and receive money from. `CLOSED`: The wallet is closed. Any transactions made to or from this wallet will error. Possible values: `UNKNOWN`, `ACTIVE`, `CLOSED` string Cursor used for fetching e-wallets created before the latest e-wallet provided in this response string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "wallets": [ { "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88", "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6", "balance": { "iso_currency_code": "GBP", "current": 123.12, "available": 100.96 }, "numbers": { "bacs": { "account": "12345678", "sort_code": "123456" } }, "status": "ACTIVE" }, { "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a999", "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f7", "balance": { "iso_currency_code": "EUR", "current": 456.78, "available": 100.96 }, "numbers": { "international": { "iban": "GB22HBUK40221241555626", "bic": "HBUKGB4B" } }, "status": "ACTIVE" } ], "request_id": "4zlKapIkTm8p5KM" } ``` \=\*=\*=\*= #### /wallet/transaction/execute  #### Execute a transaction using an e-wallet  Execute a transaction using the specified e-wallet. Specify the e-wallet to debit from, the counterparty to credit to, the idempotency key to prevent duplicate transactions, the amount and reference for the transaction. Transactions will settle in seconds to several days, depending on the underlying payment rail. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string A random key provided by the client, per unique wallet transaction. Maximum of 128 characters. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a wallet transaction fails due to a network connection error, then after a minimum delay of one minute, you can retry the request with the same idempotency key to guarantee that only a single wallet transaction is created. If the request was successfully processed, it will prevent any transaction that uses the same idempotency key, and was received within 24 hours of the first request, from being processed. Max length: `128` Min length: `1` required, string The ID of the e-wallet to debit from Min length: `1` required, object An object representing the e-wallet transaction's counterparty required, string The name of the counterparty Min length: `1` required, object The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required. object The account number and sort code of the counterparty's account string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` object International Bank Account Number for a Wallet Transaction string International Bank Account Number (IBAN). Min length: `15` Max length: `34` object The optional address of the payment recipient's bank account. Required by most institutions outside of the UK. required, \[string\] An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: `1` Min length: `1` required, string The city where the recipient is located. Maximum of 35 characters. Min length: `1` Max length: `35` required, string The postal code where the recipient is located. Maximum of 16 characters. Min length: `1` Max length: `16` required, string The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: `2` Max length: `2` string The counterparty's birthdate, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format. Format: `date` required, object The amount and currency of a transaction required, string An ISO-4217 currency code, used with e-wallets and transactions. Possible values: `GBP`, `EUR` Min length: `3` Max length: `3` required, number The amount of the transaction. Must contain at most two digits of precision e.g. `1.23`. Format: `double` Minimum: `0.01` required, string A reference for the transaction. This must be an alphanumeric string with 6 to 18 characters and must not contain any special characters or spaces. Ensure that the `reference` field is unique for each transaction. Max length: `18` Min length: `6` object The original source of the funds. This field is required by local regulation for certain businesses (e.g. money remittance) to send payouts to recipients in the EU and UK. required, string The full name associated with the source of the funds. required, object The optional address of the payment recipient's bank account. Required by most institutions outside of the UK. required, \[string\] An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: `1` Min length: `1` required, string The city where the recipient is located. Maximum of 35 characters. Min length: `1` Max length: `35` required, string The postal code where the recipient is located. Maximum of 16 characters. Min length: `1` Max length: `16` required, string The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: `2` Max length: `2` required, string The account number from which the funds are sourced. required, string The Business Identifier Code, also known as SWIFT code, for this bank account. Min length: `8` Max length: `11` ```go counterpartyBACS := plaid.NewWalletTransactionCounterpartyBACS() counterpartyBACS.SetAccount("12345678") counterpartyBACS.SetSortCode("123456") request := plaid.NewWalletTransactionExecuteRequest( "39fae5f2-b2b4-48b6-a363-5328995b2753", walletID, plaid.WalletTransactionCounterparty{ Name: "Test", Numbers: plaid.WalletTransactionCounterpartyNumbers{ Bacs: &counterpartyBACS, }, }, plaid.WalletTransactionAmount{ Value: 1.00, IsoCurrencyCode: plaid.WALLETISOCURRENCYCODE_GBP, }, "transaction ABC123", ) response, _, err := client.PlaidApi.WalletTransactionExecute(ctx).WalletTransactionExecuteRequest(*request).Execute() transactionID := response.GetTransactionId() status := response.GetStatus() ``` ```java WalletTransactionCounterparty counterparty = new WalletTransactionCounterparty() .name("Test") .numbers(new WalletTransactionCounterpartyNumbers() .bacs(new WalletTransactionCounterpartyBACS() .account("12345678") .sortCode("123456") ) ); WalletTransactionAmount amount = new WalletTransactionAmount() .value(1.00) .isoCurrencyCode(WalletISOCurrencyCode.GBP); WalletTransactionExecuteRequest request = new WalletTransactionExecuteRequest() .walletId(walletId) .counterparty(counterparty) .amount(amount) .reference("transaction ABC123") .idempotencyKey("39fae5f2-b2b4-48b6-a363-5328995b2753"); Response response = client() .walletTransactionExecute(request) .execute(); String transactionId = response.body().getTransactionId(); WalletTransactionStatus status = response.body().getStatus(); ``` ```ruby request = Plaid::WalletTransactionExecuteRequest.new( { wallet_id: wallet_id, counterparty: { name: 'Test', numbers: { bacs: { account: '12345678', sort_code: '123456' } } }, amount: { value: 1, iso_currency_code: 'GBP' }, reference: 'transaction ABC123', idempotency_key: '39fae5f2-b2b4-48b6-a363-5328995b2753' } ) response = client.wallet_transaction_execute(request) transaction_id = response.transaction_id status = response.status ``` ```node const request: WalletTransactionExecuteRequest = { wallet_id: walletID, counterparty: { name: 'Test', numbers: { bacs: { account: '12345678', sort_code: '123456', }, }, }, amount: { value: 1, iso_currency_code: 'GBP', }, reference: 'transaction ABC123', idempotency_key: '39fae5f2-b2b4-48b6-a363-5328995b2753', }; try { const response = await plaidClient.walletTransactionExecute(request); const transactionID = response.data.transaction_id; const status = response.data.status; } catch (error) { // handle error } ``` ```bash curl -X POST https://production.plaid.com/wallet/transaction/execute \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "wallet_id": "${WALLET_ID}", "counterparty": { "name": "Test", "numbers": { "bacs": { "account": "12345678", "sort_code": "123456" } } }, "amount": { "value": 1, "iso_currency_code": "GBP" }, "reference": "transaction ABC123", "idempotency_key": "39fae5f2-b2b4-48b6-a363-5328995b2753" }' ``` ```python request = WalletTransactionExecuteRequest( wallet_id=wallet_id, counterparty=WalletTransactionCounterparty( name='Test', numbers=WalletTransactionCounterpartyNumbers( bacs=WalletTransactionCounterpartyBACS( account='12345678', sort_code='123456' ) ) ), amount=WalletTransactionAmount( value=1, iso_currency_code='GBP' ), reference='transaction ABC123', idempotency_key='39fae5f2-b2b4-48b6-a363-5328995b2753' ) response = client.wallet_transaction_execute(request) transaction_id = response['transaction_id'] status = response['status'] ``` #### Response fields  string A unique ID identifying the transaction string The status of the transaction. `AUTHORISING`: The transaction is being processed for validation and compliance. `INITIATED`: The transaction has been initiated and is currently being processed. `EXECUTED`: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. `SETTLED`: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. `FAILED`: The transaction failed to process successfully. This is a terminal status. `BLOCKED`: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: `AUTHORISING`, `INITIATED`, `EXECUTED`, `SETTLED`, `BLOCKED`, `FAILED` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "transaction_id": "wallet-transaction-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88", "status": "EXECUTED", "request_id": "4zlKapIkTm8p5KM" } ``` \=\*=\*=\*= #### /wallet/transaction/get  #### Fetch an e-wallet transaction  Fetch a specific e-wallet transaction #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the transaction to fetch Min length: `1` ```go request := plaid.NewWalletTransactionGetRequest(transactionID) response, _, err := client.PlaidApi.WalletTransactionGet(ctx).WalletTransactionGetRequest(*request).Execute() transactionID := response.GetTransactionId() reference := response.GetReference() type := response.GetType() amount := response.GetAmount() counterparty := response.GetCounterparty() status := response.GetStatus() createdAt := response.GetCreatedAt() ``` ```java WalletTransactionGetRequest request = new WalletTransactionGetRequest() .transactionId(transactionId); Response response = client() .walletTransactionGet(request) .execute(); String transactionId = response.body().getTransactionId(); String reference = response.body().getReference(); TypeEnum type = response.body().getType(); WalletTransactionAmount amount = response.body().getAmount(); WalletTransactionCounterparty counterparty = response.body().getCounterparty(); WalletTransactionStatus status = response.body().getStatus(); OffsetDateTime createdAt = response.body().getCreatedAt(); ``` ```ruby request = Plaid::WalletTransactionGetRequest.new({ transaction_id: transaction_id }) response = client.wallet_transaction_get(request) transaction_id = response.transaction_id reference = response.reference type = response.type amount = response.amount counterparty = response.counterparty status = response.status createdAt = response.createdAt ``` ```node const request: WalletTransactionGetRequest = { transaction_id: transactionID, }; try { const response = await plaidClient.walletTransactionGet(request); const transactionID = response.data.transaction_id; const reference = response.data.reference; const type = response.data.type; const amount = response.data.amount; const counterparty = response.data.counterparty; const status = response.data.status; const createdAt = response.data.created_at; } catch (error) { // handle error } ``` ```bash curl -X POST https://production.plaid.com/wallet/transaction/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "transaction_id": "${TRANSACTION_ID}" }' ``` ```python request = WalletTransactionGetRequest(transaction_id=transaction_id) response = client.wallet_transaction_get(request) transaction_id = response['transaction_id'] reference = response['reference'] type = response['type'] amount = response['amount'] counterparty = response['counterparty'] status = response['status'] created_at = response['created_at'] ``` #### Response fields  string A unique ID identifying the transaction string The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests. string A reference for the transaction string The type of the transaction. The supported transaction types that are returned are: `BANK_TRANSFER:` a transaction which credits an e-wallet through an external bank transfer. `PAYOUT:` a transaction which debits an e-wallet by disbursing funds to a counterparty. `PIS_PAY_IN:` a payment which credits an e-wallet through Plaid's Payment Initiation Services (PIS) APIs. For more information see the [Payment Initiation endpoints](https://plaid.com/docs/api/products/payment-initiation/index.html.md) . `REFUND:` a transaction which debits an e-wallet by refunding a previously initiated payment made through Plaid's [PIS APIs](https://plaid.com/docs/api/products/payment-initiation/index.html.md) . `FUNDS_SWEEP`: an automated transaction which debits funds from an e-wallet to a designated client-owned account. `RETURN`: an automated transaction where a debit transaction was reversed and money moved back to originating account. `RECALL`: a transaction where the sending bank has requested the return of funds due to a fraud claim, technical error, or other issue associated with the payment. Possible values: `BANK_TRANSFER`, `PAYOUT`, `PIS_PAY_IN`, `REFUND`, `FUNDS_SWEEP`, `RETURN`, `RECALL` nullable, string The payment scheme used to execute this transaction. This is present only for transaction types `PAYOUT` and `REFUND`. `FASTER_PAYMENTS`: The standard payment scheme within the UK. `SEPA_CREDIT_TRANSFER`: The standard payment to a beneficiary within the SEPA area. `SEPA_CREDIT_TRANSFER_INSTANT`: Instant payment to a beneficiary within the SEPA area. Possible values: `null`, `FASTER_PAYMENTS`, `SEPA_CREDIT_TRANSFER`, `SEPA_CREDIT_TRANSFER_INSTANT` object The amount and currency of a transaction string An ISO-4217 currency code, used with e-wallets and transactions. Possible values: `GBP`, `EUR` Min length: `3` Max length: `3` number The amount of the transaction. Must contain at most two digits of precision e.g. `1.23`. Format: `double` Minimum: `0.01` object An object representing the e-wallet transaction's counterparty string The name of the counterparty Min length: `1` object The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required. nullable, object The account number and sort code of the counterparty's account string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` nullable, object International Bank Account Number for a Wallet Transaction string International Bank Account Number (IBAN). Min length: `15` Max length: `34` nullable, object The optional address of the payment recipient's bank account. Required by most institutions outside of the UK. \[string\] An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: `1` Min length: `1` string The city where the recipient is located. Maximum of 35 characters. Min length: `1` Max length: `35` string The postal code where the recipient is located. Maximum of 16 characters. Min length: `1` Max length: `16` string The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: `2` Max length: `2` nullable, string The counterparty's birthdate, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format. Format: `date` string The status of the transaction. `AUTHORISING`: The transaction is being processed for validation and compliance. `INITIATED`: The transaction has been initiated and is currently being processed. `EXECUTED`: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. `SETTLED`: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. `FAILED`: The transaction failed to process successfully. This is a terminal status. `BLOCKED`: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: `AUTHORISING`, `INITIATED`, `EXECUTED`, `SETTLED`, `BLOCKED`, `FAILED` string Timestamp when the transaction was created, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` string The date and time of the last time the `status` was updated, in IS0 8601 format Format: `date-time` nullable, string Result of payee verification check for EUR payouts. Payee verification checks whether the payee name provided matches the account holder name at the destination institution. `FULL_MATCH`: The payee name fully matches the account holder. `PARTIAL_MATCH`: The payee name partially matches the account holder. `NO_MATCH`: The payee name does not match the account holder. `ERROR`: An error occurred during payee verification. `CHECK_NOT_POSSIBLE`: Payee verification could not be performed. This field is only populated for applicable EUR payout transactions and will be `null` for other transaction types. Possible values: `FULL_MATCH`, `PARTIAL_MATCH`, `NO_MATCH`, `ERROR`, `CHECK_NOT_POSSIBLE` nullable, string The payment id that this transaction is associated with, if any. This is present only for transaction types `PIS_PAY_IN` and `REFUND`. nullable, string The error code of a failed transaction. Error codes include: `EXTERNAL_SYSTEM`: The transaction was declined by an external system. `EXPIRED`: The transaction request has expired. `CANCELLED`: The transaction request was rescinded. `INVALID`: The transaction did not meet certain criteria, such as an inactive account or no valid counterparty, etc. `UNKNOWN`: The transaction was unsuccessful, but the exact cause is unknown. Possible values: `EXTERNAL_SYSTEM`, `EXPIRED`, `CANCELLED`, `INVALID`, `UNKNOWN` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[object\] A list of wallet transactions that this transaction is associated with, if any. string The ID of the related transaction. string The type of the transaction. Possible values: `PAYOUT`, `RETURN`, `REFUND`, `FUNDS_SWEEP` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3", "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88", "type": "PAYOUT", "reference": "Payout 99744", "amount": { "iso_currency_code": "GBP", "value": 123.12 }, "status": "EXECUTED", "created_at": "2020-12-02T21:14:54Z", "last_status_update": "2020-12-02T21:15:01Z", "counterparty": { "numbers": { "bacs": { "account": "31926819", "sort_code": "601613" } }, "name": "John Smith" }, "request_id": "4zlKapIkTm8p5KM", "related_transactions": [ { "id": "wallet-transaction-id-sandbox-2ba30780-d549-4335-b1fe-c2a938aa39d2", "type": "RETURN" } ] } ``` \=\*=\*=\*= #### /wallet/transaction/list  #### List e-wallet transactions  This endpoint lists the latest transactions of the specified e-wallet. Transactions are returned in descending order by the `created_at` time. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the e-wallet to fetch transactions from Min length: `1` string A value representing the latest transaction to be included in the response. Set this from `next_cursor` received in the previous `/wallet/transaction/list` request. If provided, the response will only contain that transaction and transactions created before it. If omitted, the response will contain transactions starting from the most recent, and in descending order by the `created_at` time. Max length: `256` integer The number of transactions to fetch Minimum: `1` Maximum: `200` Default: `10` object Additional wallet transaction options string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DDThh:mm:ssZ) for filtering transactions, inclusive of the provided date. Format: `date-time` string Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DDThh:mm:ssZ) for filtering transactions, inclusive of the provided date. Format: `date-time` ```go request := plaid.NewWalletTransactionListRequest(walletID) request.SetCount(10) response, _, err := client.PlaidApi.WalletTransactionList(ctx).WalletTransactionListRequest(*request).Execute() transactions := response.GetTransactions() nextCursor := response.GetNextCursor() ``` ```java WalletTransactionListRequest request = new WalletTransactionListRequest() .walletId(walletId) .count(10); Response response = client() .walletTransactionList(request) .execute(); List transactions = response.body().getTransactions(); String nextCursor = response.body().getNextCursor(); ``` ```ruby request = Plaid::WalletTransactionListRequest.new( { wallet_id: wallet_id, count: 10 } ) response = client.wallet_transaction_list(request) transactions = response.transactions next_cursor = response.next_cursor ``` ```node const request: WalletTransactionListRequest = { wallet_id: walletID, count: 10, }; try { const response = await plaidClient.walletTransactionList(request); const transactions = response.data.transactions; const nextCursor = response.data.next_cursor; } catch (error) { // handle error } ``` ```bash curl -X POST https://production.plaid.com/wallet/transaction/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "wallet_id": "${WALLET_ID}", "count": 10 }' ``` ```python request = WalletTransactionListRequest( wallet_id=wallet_id, count=10 ) response = client.wallet_transaction_list(request) transactions = response['transactions'] next_cursor = response['next_cursor'] ``` #### Response fields  \[object\] An array of transactions of an e-wallet, associated with the given `wallet_id` string A unique ID identifying the transaction string The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests. string A reference for the transaction string The type of the transaction. The supported transaction types that are returned are: `BANK_TRANSFER:` a transaction which credits an e-wallet through an external bank transfer. `PAYOUT:` a transaction which debits an e-wallet by disbursing funds to a counterparty. `PIS_PAY_IN:` a payment which credits an e-wallet through Plaid's Payment Initiation Services (PIS) APIs. For more information see the [Payment Initiation endpoints](https://plaid.com/docs/api/products/payment-initiation/index.html.md) . `REFUND:` a transaction which debits an e-wallet by refunding a previously initiated payment made through Plaid's [PIS APIs](https://plaid.com/docs/api/products/payment-initiation/index.html.md) . `FUNDS_SWEEP`: an automated transaction which debits funds from an e-wallet to a designated client-owned account. `RETURN`: an automated transaction where a debit transaction was reversed and money moved back to originating account. `RECALL`: a transaction where the sending bank has requested the return of funds due to a fraud claim, technical error, or other issue associated with the payment. Possible values: `BANK_TRANSFER`, `PAYOUT`, `PIS_PAY_IN`, `REFUND`, `FUNDS_SWEEP`, `RETURN`, `RECALL` nullable, string The payment scheme used to execute this transaction. This is present only for transaction types `PAYOUT` and `REFUND`. `FASTER_PAYMENTS`: The standard payment scheme within the UK. `SEPA_CREDIT_TRANSFER`: The standard payment to a beneficiary within the SEPA area. `SEPA_CREDIT_TRANSFER_INSTANT`: Instant payment to a beneficiary within the SEPA area. Possible values: `null`, `FASTER_PAYMENTS`, `SEPA_CREDIT_TRANSFER`, `SEPA_CREDIT_TRANSFER_INSTANT` object The amount and currency of a transaction string An ISO-4217 currency code, used with e-wallets and transactions. Possible values: `GBP`, `EUR` Min length: `3` Max length: `3` number The amount of the transaction. Must contain at most two digits of precision e.g. `1.23`. Format: `double` Minimum: `0.01` object An object representing the e-wallet transaction's counterparty string The name of the counterparty Min length: `1` object The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required. nullable, object The account number and sort code of the counterparty's account string The account number of the account. Maximum of 10 characters. Min length: `1` Max length: `10` string The 6-character sort code of the account. Min length: `6` Max length: `6` nullable, object International Bank Account Number for a Wallet Transaction string International Bank Account Number (IBAN). Min length: `15` Max length: `34` nullable, object The optional address of the payment recipient's bank account. Required by most institutions outside of the UK. \[string\] An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters. Min items: `1` Min length: `1` string The city where the recipient is located. Maximum of 35 characters. Min length: `1` Max length: `35` string The postal code where the recipient is located. Maximum of 16 characters. Min length: `1` Max length: `16` string The ISO 3166-1 alpha-2 country code where the recipient is located. Min length: `2` Max length: `2` nullable, string The counterparty's birthdate, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format. Format: `date` string The status of the transaction. `AUTHORISING`: The transaction is being processed for validation and compliance. `INITIATED`: The transaction has been initiated and is currently being processed. `EXECUTED`: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. `SETTLED`: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. `FAILED`: The transaction failed to process successfully. This is a terminal status. `BLOCKED`: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: `AUTHORISING`, `INITIATED`, `EXECUTED`, `SETTLED`, `BLOCKED`, `FAILED` string Timestamp when the transaction was created, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. Format: `date-time` string The date and time of the last time the `status` was updated, in IS0 8601 format Format: `date-time` nullable, string Result of payee verification check for EUR payouts. Payee verification checks whether the payee name provided matches the account holder name at the destination institution. `FULL_MATCH`: The payee name fully matches the account holder. `PARTIAL_MATCH`: The payee name partially matches the account holder. `NO_MATCH`: The payee name does not match the account holder. `ERROR`: An error occurred during payee verification. `CHECK_NOT_POSSIBLE`: Payee verification could not be performed. This field is only populated for applicable EUR payout transactions and will be `null` for other transaction types. Possible values: `FULL_MATCH`, `PARTIAL_MATCH`, `NO_MATCH`, `ERROR`, `CHECK_NOT_POSSIBLE` nullable, string The payment id that this transaction is associated with, if any. This is present only for transaction types `PIS_PAY_IN` and `REFUND`. nullable, string The error code of a failed transaction. Error codes include: `EXTERNAL_SYSTEM`: The transaction was declined by an external system. `EXPIRED`: The transaction request has expired. `CANCELLED`: The transaction request was rescinded. `INVALID`: The transaction did not meet certain criteria, such as an inactive account or no valid counterparty, etc. `UNKNOWN`: The transaction was unsuccessful, but the exact cause is unknown. Possible values: `EXTERNAL_SYSTEM`, `EXPIRED`, `CANCELLED`, `INVALID`, `UNKNOWN` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[object\] A list of wallet transactions that this transaction is associated with, if any. string The ID of the related transaction. string The type of the transaction. Possible values: `PAYOUT`, `RETURN`, `REFUND`, `FUNDS_SWEEP` string The value that, when used as the optional `cursor` parameter to `/wallet/transaction/list`, will return the corresponding transaction as its first entry. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "next_cursor": "YWJjMTIzIT8kKiYoKSctPUB", "transactions": [ { "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3", "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88", "type": "PAYOUT", "reference": "Payout 99744", "amount": { "iso_currency_code": "GBP", "value": 123.12 }, "status": "EXECUTED", "created_at": "2020-12-02T21:14:54Z", "last_status_update": "2020-12-02T21:15:01Z", "counterparty": { "numbers": { "bacs": { "account": "31926819", "sort_code": "601613" } }, "name": "John Smith" }, "related_transactions": [ { "id": "wallet-transaction-id-sandbox-2ba30780-d549-4335-b1fe-c2a938aa39d2", "type": "RETURN" } ] }, { "transaction_id": "wallet-transaction-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3", "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88", "type": "PAYOUT", "reference": "Payout 99744", "amount": { "iso_currency_code": "EUR", "value": 456.78 }, "status": "EXECUTED", "created_at": "2020-12-02T21:14:54Z", "last_status_update": "2020-12-02T21:15:01Z", "counterparty": { "numbers": { "international": { "iban": "GB33BUKB20201555555555" } }, "name": "John Smith" }, "related_transactions": [] } ], "request_id": "4zlKapIkTm8p5KM" } ``` ### Webhooks  Updates are sent to indicate that the status of transaction has changed. All virtual account webhooks have a `webhook_type` of `WALLET`. \=\*=\*=\*= #### WALLET\_TRANSACTION\_STATUS\_UPDATE  Fired when the status of a wallet transaction has changed. #### Properties  string `WALLET` string `WALLET_TRANSACTION_STATUS_UPDATE` string The `transaction_id` for the wallet transaction being updated string The `payment_id` associated with the transaction. This will be present in case of `REFUND` and `PIS_PAY_IN`. string The EMI (E-Money Institution) wallet that this payment is associated with. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests. string The status of the transaction. `AUTHORISING`: The transaction is being processed for validation and compliance. `INITIATED`: The transaction has been initiated and is currently being processed. `EXECUTED`: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. `SETTLED`: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. `FAILED`: The transaction failed to process successfully. This is a terminal status. `BLOCKED`: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: `AUTHORISING`, `INITIATED`, `EXECUTED`, `SETTLED`, `BLOCKED`, `FAILED` string The status of the transaction. `AUTHORISING`: The transaction is being processed for validation and compliance. `INITIATED`: The transaction has been initiated and is currently being processed. `EXECUTED`: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions. `SETTLED`: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used. `FAILED`: The transaction failed to process successfully. This is a terminal status. `BLOCKED`: The transaction has been blocked for violating compliance rules. This is a terminal status. Possible values: `AUTHORISING`, `INITIATED`, `EXECUTED`, `SETTLED`, `BLOCKED`, `FAILED` string The timestamp of the update, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format, e.g. `"2017-09-14T14:42:19.350Z"` Format: `date-time` object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. string The Plaid environment the webhook was sent from Possible values: `sandbox`, `production` API Object ```json { "webhook_type": "WALLET", "webhook_code": "WALLET_TRANSACTION_STATUS_UPDATE", "transaction_id": "wallet-transaction-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2", "payment_id": "payment-id-production-feca8a7a-5591-4aef-9297-f3062bb735d3", "wallet_id": "wallet-id-production-53e58b32-fc1c-46fe-bbd6-e584b27a88", "new_status": "SETTLED", "old_status": "INITIATED", "timestamp": "2017-09-14T14:42:19.350Z", "environment": "production" } ``` --- # API - Sandbox | Plaid Docs Sandbox endpoints  ================== #### API reference for Sandbox endpoints  #### Introduction  Plaid's Sandbox environment provides a number of endpoints that can be used to configure testing scenarios. These endpoints are unique to the Sandbox environment and cannot be used in Production. For more information on these endpoints, see [Sandbox](https://plaid.com/docs/sandbox/index.html.md) . | In this section | | | --- | --- | | [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) | Bypass the Link flow for creating an Item | | [/sandbox/processor\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxprocessor_tokencreate) | Bypass the Link flow for creating an Item for a processor partner | | [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) | Trigger the `ITEM_LOGIN_REQUIRED` state for an Item | | [/sandbox/user/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxuserreset_login) | (Income and Check) Force Item(s) for a Sandbox user into an error state | | [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) | Fire a specific webhook | | [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) | (Auth) Set a verification status for testing micro-deposits | | [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) | (Transfer) Fire a specific webhook | | [/sandbox/transfer/ledger/deposit/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerdepositsimulate) | (Transfer) Simulate a deposit sweep event | | [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) | (Transfer) Simulate converting pending balance into available balance | | [/sandbox/transfer/ledger/withdraw/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerwithdrawsimulate) | (Transfer) Simulate a withdraw sweep event | | [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) | (Transfer) Simulate a transfer event | | [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) | (Transfer) Simulate a refund event | | [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) | (Transfer) Create a test clock for testing recurring transfers | | [/sandbox/transfer/test\_clock/advance](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockadvance) | (Transfer) Advance the time on a test clock | | [/sandbox/transfer/test\_clock/get](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockget) | (Transfer) Get details about a test clock | | [/sandbox/transfer/test\_clock/list](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clocklist) | (Transfer) Get details about all test clocks | | [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) | (Income) Fire a specific webhook | | [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) | (Check) Simulate an update for Cash Flow Updates | | [/sandbox/payment/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpaymentsimulate) | (Payment Initiation) Simulate a payment | | [/sandbox/transactions/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransactionscreate) | (Transactions) Create custom transactions for Items | \=\*=\*=\*= #### /sandbox/public\_token/create  #### Create a test Item  Use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint to create a valid `public_token` for an arbitrary institution ID, initial products, and test credentials. The created `public_token` maps to a new Sandbox Item. You can then call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` for an `access_token` and perform all API actions. [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) can also be used with the [user\_custom test username](https://plaid.com/docs/sandbox/user-custom/index.html.md) to generate a test account with custom data, or with Plaid's [pre-populated Sandbox test accounts](https://plaid.com/docs/sandbox/test-credentials/index.html.md) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the institution the Item will be associated with required, \[string\] The products to initially pull for the Item. May be any products that the specified `institution_id` supports. This array may not be empty. Min items: `1` Possible values: `assets`, `auth`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_monitoring`, `identity`, `income_verification`, `investments_auth`, `investments`, `liabilities`, `payment_initiation`, `signal`, `standing_orders`, `statements`, `transactions`, `transfer` object An optional set of options to be used when configuring the Item. If specified, must not be `null`. string Specify a webhook to associate with the new Item. Format: `url` string Test username to use for the creation of the Sandbox Item. Default value is `user_good`. Default: `user_good` string Test password to use for the creation of the Sandbox Item. Default value is `pass_good`. Default: `pass_good` object An optional set of parameters corresponding to transactions options. string The earliest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. Format: `date` string The most recent date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. Format: `date` object An optional set of parameters corresponding to statements options. required, string The earliest date for which to fetch statements history. Dates should be formatted as YYYY-MM-DD. Format: `date` required, string The most recent date for which to fetch statements history. Dates should be formatted as YYYY-MM-DD. Format: `date` object A set of parameters for income verification options. This field is required if `income_verification` is included in the `initial_products` array. \[string\] The types of source income data that users will be permitted to share. Options include `bank` and `payroll`. Currently you can only specify one of these options. Possible values: `bank`, `payroll` object Specifies options for Bank Income. This field is required if `income_verification` is included in the `initial_products` array and `bank` is specified in `income_source_types`. integer The number of days of data to request for the Bank Income product string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/sandbox/public_token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "institution_id": String, "initial_products": [String], "options": { "webhook": String, "override_username": String, "override_password": String } }' ``` ```node const publicTokenRequest: SandboxPublicTokenCreateRequest = { institution_id: institutionID, initial_products: initialProducts, }; try { const publicTokenResponse = await client.sandboxPublicTokenCreate( publicTokenRequest, ); const publicToken = publicTokenResponse.data.public_token; // The generated public_token can now be exchanged // for an access_token const exchangeRequest: ItemPublicTokenExchangeRequest = { public_token: publicToken, }; const exchangeTokenResponse = await client.itemPublicTokenExchange( exchangeRequest, ); const accessToken = exchangeTokenResponse.data.access_token; } catch (error) { // handle error } ``` ```python pt_request = SandboxPublicTokenCreateRequest( institution_id=INSTITUTION_ID, initial_products=[Products('transactions')] ) pt_response = client.sandbox_public_token_create(pt_request) # The generated public_token can now be # exchanged for an access_token exchange_request = ItemPublicTokenExchangeRequest( public_token=pt_response['public_token'] ) exchange_response = client.item_public_token_exchange(exchange_request) ``` ```java SandboxPublicTokenCreateRequest createRequest = new SandboxPublicTokenCreateRequest() .institutionId(TARTAN_BANK_INSTITUTION_ID) .initialProducts(Arrays.asList(Products.AUTH)); Response createResponse = client .sandboxPublicTokenCreate(createRequest) .execute(); // The generated public_token can now be // exchanged for an access_token ItemPublicTokenExchangeRequest exchangeRequest = new ItemPublicTokenExchangeRequest() .publicToken(createResponse.body().getPublicToken()); Response response = client .itemPublicTokenExchange(exchangeRequest) .execute(); ``` ```ruby request = Plaid::SandboxPublicTokenCreateRequest.new( { institution_id: SANDBOX_INSTITUTION, initial_products: ["transactions"] } ) response = client.sandbox_public_token_create(request) # The generated public_token can now be # exchanged for an access_token publicToken = response.public_token item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: publicToken } ) response = client.item_public_token_exchange(item_public_token_exchange_request) ``` ```go sandboxPublicTokenResp, _, err := client.PlaidApi.SandboxPublicTokenCreate(ctx).SandboxPublicTokenCreateRequest( *plaid.NewSandboxPublicTokenCreateRequest( institutionID, products, ), ).Execute() // exchange the public_token for an access_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest(sandboxPublicTokenResp.GetPublicToken()), ).Execute() ``` #### Response fields  string A public token that can be exchanged for an access token using `/item/public_token/exchange` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", "request_id": "Aim3b" } ``` \=\*=\*=\*= #### /sandbox/processor\_token/create  #### Create a test Item and processor token  Use the [/sandbox/processor\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxprocessor_tokencreate) endpoint to create a valid `processor_token` for an arbitrary institution ID and test credentials. The created `processor_token` corresponds to a new Sandbox Item. You can then use this `processor_token` with the `/processor/` API endpoints in Sandbox. You can also use [/sandbox/processor\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxprocessor_tokencreate) with the [user\_custom test username](https://plaid.com/docs/sandbox/user-custom/index.html.md) to generate a test account with custom data. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the institution the Item will be associated with object An optional set of options to be used when configuring the Item. If specified, must not be `null`. string Test username to use for the creation of the Sandbox Item. Default value is `user_good`. Default: `user_good` string Test password to use for the creation of the Sandbox Item. Default value is `pass_good`. Default: `pass_good` ```bash curl -X POST https://sandbox.plaid.com/sandbox/processor_token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "institution_id": String, "options": { "override_username": String, "override_password": String } }' ``` ```node const request: SandboxProcessorTokenCreateRequest = { institution_id: institutionID, }; try { const response = await plaidClient.sandboxProcessorTokenCreate(request); const processorToken = response.data.processor_token; } catch (error) { // handle error } ``` ```python request = SandboxProcessorTokenCreate(institution_id=INSTITUTION_ID) response = client.sandbox_processor_token_create(request) processor_token = response['processor_token'] # The generated processor_token can now be used to call # processor endpoints. These endpoints are not currently # accessible via the client libraries. ``` ```java SandboxProcessorTokenCreateRequest request = new SandboxProcessorTokenCreateRequest() .institutionId(INSTITUTION_ID); Response response = client() .sandboxProcessorTokenCreate(request) .execute(); String processorToken = response.body().getProcessorToken(); // The generated processor_token can now be used to call // processor endpoints. These endpoints are not currently // accessible via the client libraries. ``` ```ruby request = Plaid::SandboxProcessorTokenCreateRequest.new( { institution_id: INSTITUTION_ID } ) response = client.sandbox_processor_token_create(request) processor_token = response.processor_token # The generated processor_token can now be used to call # processor endpoints. These endpoints are not currently # accessible via the client libraries. ``` ```go request := plaid.NewSandboxProcessorTokenCreateRequest("INSTITUTION_ID") processorTokenResp, _, err := client.SandboxProcessorTokenCreate(ctx).SandboxProcessorTokenCreateRequest( *request, ).Execute() ``` #### Response fields  string A processor token that can be used to call the `/processor/` endpoints. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "processor_token": "processor-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", "request_id": "Aim3b" } ``` \=\*=\*=\*= #### /sandbox/item/reset\_login  #### Force a Sandbox Item into an error state  `/sandbox/item/reset_login/` forces an Item into an `ITEM_LOGIN_REQUIRED` state in order to simulate an Item whose login is no longer valid. This makes it easy to test Link's [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow in the Sandbox environment. After calling [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) , You can then use Plaid Link update mode to restore the Item to a good state. An `ITEM_LOGIN_REQUIRED` webhook will also be fired after a call to this endpoint, if one is associated with the Item. In the Sandbox, Items will transition to an `ITEM_LOGIN_REQUIRED` error state automatically after 30 days, even if this endpoint is not called. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. ```bash curl -X POST https://sandbox.plaid.com/sandbox/item/reset_login \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node const request: SandboxItemResetLoginRequest = { access_token: accessToken, }; try { const response = await plaidClient.sandboxItemResetLogin(request); } catch (error) { // handle error } ``` ```python # force a Sandbox Item into an ITEM_LOGIN_REQUIRED state request = SandboxItemResetLoginRequest(access_token=access_token) response = client.sandbox_item_reset_login(request) ``` ```java SandboxItemResetLoginRequest request = new SandboxItemResetLoginRequest() .accessToken(accessToken); Response response = client() .sandboxItemResetLogin(request) .execute(); ``` ```ruby # force a Sandbox Item into an error state request = Plaid::SandboxItemResetLoginRequest.new({ access_token: accessToken }) response = client.sandbox_item_reset_login(request) ``` ```go // force a Sandbox Item into an error state resetResp, _, err := client.PlaidApi.SandboxItemResetLogin(ctx).SandboxItemResetLoginRequest( *plaid.NewSandboxItemResetLoginRequest( accessToken, ), ).Execute() // create a public_token for the Item and use it to // initialize Link in update mode. publicTokenResp, _, err := client.PlaidApi.ItemCreatePublicToken(ctx).ItemPublicTokenCreateRequest( *plaid.NewItemPublicTokenCreateRequest( accessToken, ), ).Execute() ``` #### Response fields  boolean `true` if the call succeeded string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "reset_login": true, "request_id": "m8MDnv9okwxFNBV" } ``` \=\*=\*=\*= #### /sandbox/user/reset\_login  #### Force item(s) for a Sandbox User into an error state  `/sandbox/user/reset_login/` functions the same as [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) , but will modify Items related to a User. This endpoint forces each Item into an `ITEM_LOGIN_REQUIRED` state in order to simulate an Item whose login is no longer valid. This makes it easy to test Link's [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow in the Sandbox environment. After calling [/sandbox/user/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxuserreset_login) , You can then use Plaid Link update mode to restore Items associated with the User to a good state. An `ITEM_LOGIN_REQUIRED` webhook will also be fired after a call to this endpoint, if one is associated with the Item. In the Sandbox, Items will transition to an `ITEM_LOGIN_REQUIRED` error state automatically after 30 days, even if this endpoint is not called. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . \[string\] An array of `item_id`s associated with the User to be reset. If empty or `null`, this field will default to resetting all Items associated with the User. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/sandbox/user/reset_login \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw", "item_ids": [ "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", ] }' ``` ```node const request: SandboxUserResetLoginRequest = { user_id: 'usr_9nSp2KuZ2x4JDw', item_ids: ['eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6'] }; try { const response = await plaidClient.sandboxUserResetLogin(request); } catch (error) { // handle error } ``` ```python # force a Sandbox Item for a user into an error state request = SandboxUserResetLoginRequest( user_id='usr_9nSp2KuZ2x4JDw', item_ids=['eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6'] ) response = client.sandbox_user_reset_login(request) ``` ```java // force a Sandbox Item for a user into an error state SandboxUserResetLoginRequest request = new SandboxUserResetLoginRequest() .userId("usr_9nSp2KuZ2x4JDw") .itemIds(Arrays.asList( "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6" )); Response response = client() .sandboxUserResetLogin(request) .execute(); ``` ```ruby # force a Sandbox Item for a user into an error state request = Plaid::SandboxUserResetLoginRequest.new({ user_id: "usr_9nSp2KuZ2x4JDw", item_ids: ["eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6"] }) response = client.sandbox_user_reset_login(request) ``` ```go // force a Sandbox Item for a user into an error state request := plaid.SandboxUserResetLoginRequest{ UserId: plaid.PtrString("usr_9nSp2KuZ2x4JDw"), ItemIds: []string{"eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6"}, } resetResp, _, err := client.PlaidApi. SandboxUserResetLogin(ctx). SandboxUserResetLoginRequest(request). Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "n7XQnv8ozwyFPBC" } ``` \=\*=\*=\*= #### /sandbox/item/fire\_webhook  #### Fire a test webhook  The [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) endpoint is used to test that code correctly handles webhooks. This endpoint can trigger the following webhooks: `DEFAULT_UPDATE`: Webhook to be fired for a given Sandbox Item simulating a default update event for the respective product as specified with the `webhook_type` in the request body. Valid Sandbox `DEFAULT_UPDATE` webhook types include: `AUTH`, `IDENTITY`, `TRANSACTIONS`, `INVESTMENTS_TRANSACTIONS`, `LIABILITIES`, `HOLDINGS`. If the Item does not support the product, a `SANDBOX_PRODUCT_NOT_ENABLED` error will result. `NEW_ACCOUNTS_AVAILABLE`: Fired to indicate that a new account is available on the Item and you can launch update mode to request access to it. `SMS_MICRODEPOSITS_VERIFICATION`: Fired when a given same day micro-deposit item is verified via SMS verification. `LOGIN_REPAIRED`: Fired when an Item recovers from the `ITEM_LOGIN_REQUIRED` without the user going through update mode in your app. `PENDING_DISCONNECT`: Fired when an Item will stop working in the near future (e.g. due to a planned bank migration) and must be sent through update mode to continue working. `RECURRING_TRANSACTIONS_UPDATE`: Recurring Transactions webhook to be fired for a given Sandbox Item. If the Item does not support Recurring Transactions, a `SANDBOX_PRODUCT_NOT_ENABLED` error will result. `SYNC_UPDATES_AVAILABLE`: Transactions webhook to be fired for a given Sandbox Item. If the Item does not support Transactions, a `SANDBOX_PRODUCT_NOT_ENABLED` error will result. `PRODUCT_READY`: Assets webhook to be fired when a given asset report has been successfully generated. If the Item does not support Assets, a `SANDBOX_PRODUCT_NOT_ENABLED` error will result. `ERROR`: Assets webhook to be fired when asset report generation has failed. If the Item does not support Assets, a `SANDBOX_PRODUCT_NOT_ENABLED` error will result. `USER_PERMISSION_REVOKED`: Indicates an end user has revoked the permission that they previously granted to access an Item. May not always fire upon revocation, as some institutions’ consent portals do not trigger this webhook. Upon receiving this webhook, it is recommended to delete any stored data from Plaid associated with the account or Item. `USER_ACCOUNT_REVOKED`: Fired when an end user has revoked access to their account on the Data Provider's portal. This webhook is currently sent only for PNC Items, but may be sent in the future for other financial institutions. Upon receiving this webhook, it is recommended to delete any stored data from Plaid associated with the account or Item. Note that this endpoint is provided for developer ease-of-use and is not required for testing webhooks; webhooks will also fire in Sandbox under the same conditions that they would in Production (except for webhooks of type `TRANSFER`). #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. string The webhook types that can be fired by this test endpoint. Possible values: `AUTH`, `HOLDINGS`, `INVESTMENTS_TRANSACTIONS`, `ITEM`, `LIABILITIES`, `TRANSACTIONS`, `ASSETS` required, string The webhook codes that can be fired by this test endpoint. Possible values: `DEFAULT_UPDATE`, `NEW_ACCOUNTS_AVAILABLE`, `SMS_MICRODEPOSITS_VERIFICATION`, `USER_PERMISSION_REVOKED`, `USER_ACCOUNT_REVOKED`, `PENDING_DISCONNECT`, `RECURRING_TRANSACTIONS_UPDATE`, `LOGIN_REPAIRED`, `SYNC_UPDATES_AVAILABLE`, `PRODUCT_READY`, `ERROR` ```bash curl -X POST https://sandbox.plaid.com/sandbox/item/fire_webhook \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "webhook_code": String }' ``` ```node // Fire a DEFAULT_UPDATE webhook for an Item const request: SandboxItemFireWebhookRequest = { access_token: accessToken, webhook_code: 'DEFAULT_UPDATE' }; try { const response = await plaidClient.sandboxItemFireWebhook(request); } catch (error) { // handle error } ``` ```python # fire a DEFAULT_UPDATE webhook for an item request = SandboxItemFireWebhookRequest( access_token=access_token, webhook_code='DEFAULT_UPDATE' ) response = client.sandbox_item_fire_webhook(request) ``` ```java // fire a DEFAULT_UPDATE webhook for an Item SandboxItemFireWebhookRequest request = new SandboxItemFireWebhookRequest() .accessToken(accessToken) .webhookCode("DEFAULT_UPDATE"); Response response = client() .sandboxItemFireWebhook(request) .execute(); ``` ```ruby # fire a DEFAULT_UPDATE webhook for an item request = Plaid::SandboxItemFireWebhookRequest.new( { access_token: access_token, webhook_code: "DEFAULT_UPDATE" } ) response = client.sandbox_item_fire_webhook(request) ``` ```go request := plaid.NewSandboxItemFireWebhookRequest(accessToken, "DEFAULT_UPDATE") fireWebhookResp, _, err := client.PlaidApi.SandboxItemFireWebhook(ctx).SandboxItemFireWebhookRequest( *request, ).Execute() ``` #### Response fields  boolean Value is `true` if the test `webhook_code` was successfully fired. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "webhook_fired": true, "request_id": "1vwmF5TBQwiqfwP" } ``` \=\*=\*=\*= #### /sandbox/item/set\_verification\_status  #### Set verification status for Sandbox account  The [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) endpoint can be used to change the verification status of an Item in in the Sandbox in order to simulate the Automated Micro-deposit flow. For more information on testing Automated Micro-deposits in Sandbox, see [Auth full coverage testing](https://plaid.com/docs/auth/coverage/testing/index.html.md#) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. required, string The `account_id` of the account whose verification status is to be modified required, string The verification status to set the account to. Possible values: `automatically_verified`, `verification_expired` ```bash curl -X POST https://sandbox.plaid.com/sandbox/item/set_verification_status \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "account_id": String, "verification_status": String }' ``` ```node const request: SandboxItemSetVerificationStatusRequest = { access_token: accessToken, account_id: accountID, verification_status: 'automatically_verified', }; try { const response = await plaidClient.sandboxItemSetVerificationStatus(request); } catch (error) { // handle error } ``` ```python # Set the verification_status for an Item created using Automated Microdeposits, triggering a webhook request = SandboxItemSetVerificationStatus( access_token=access_token, account_id=account_id, verification_status="automatically_verified" ) response = client.sandbox_item_set_verification_status(request) ``` ```java // Set the verification_status for an Item created using Automated Microdeposits, triggering a webhook SandboxItemSetVerificationStatusRequest request = new SandboxItemSetVerificationStatusRequest() .accessToken(accessToken) .accountId(accountId) .verificationStatus("automatically_verified"); Response response = client() .sandboxItemSetVerificationStatus(request) .execute(); ``` ```ruby # Set the verification_status for an Item created using Automated Microdeposits, triggering a webhook request = Plaid::SandboxItemSetVerificationStatusRequest.new( { access_token: access_token, account_id: account_id, verification_status: 'automatically_verified' } ) response = client.sandbox_item_set_verification_status(request) ``` ```go // Set the verification_status for an Item created using Automated Microdeposits, triggering a webhook setVerificationStatusResp, _, err := client.PlaidApi.SandboxItemSetVerificationStatus(ctx).SandboxItemSetVerificationStatusRequest( *plaid.NewSandboxItemSetVerificationStatusRequest( accessToken, accountID, "automatically_verified", ), ).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "1vwmF5TBQwiqfwP" } ``` \=\*=\*=\*= #### /sandbox/transfer/fire\_webhook  #### Manually fire a Transfer webhook  Use the [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) endpoint to manually trigger a `TRANSFER_EVENTS_UPDATE` webhook in the Sandbox environment. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The URL to which the webhook should be sent. Format: `url` ```bash curl -X POST https://sandbox.plaid.com/sandbox/transfer/fire_webhook \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "webhook": String }' ``` ```node const request: SandboxTransferFireWebhookRequest = { webhook: 'https://www.example.com', }; try { const response = await plaidClient.sandboxTransferFireWebhook(request); // empty response upon success } catch (error) { // handle error } ``` ```python response = client.Sandbox.transfer.fire_webhook( webhook_url, ) # empty response upon success ``` ```java SandboxTransferFireWebhookRequest request = new SandboxTransferFireWebhookRequest() .webhook(webhookUrl); Response response = client() .sandboxTransferFireWebhook(request) .execute(); // empty response upon success ``` ```ruby request = Plaid::SandboxTransferFireWebhookRequest.new( { webhook: "https://www.example.com" } ) response = client.sandbox_transfer_fire_webhook(request) # empty response upon success ``` ```go request := plaid.NewSandboxTransferFireWebhookRequest(webhookUrl) response, _, err := client.PlaidApi.SandboxTransferFireWebhook(ctx).SandboxTransferFireWebhookRequest( *request, ).Execute() // empty response upon success ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/transfer/simulate  #### Simulate a transfer event in Sandbox  Use the [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) endpoint to simulate a transfer event in the Sandbox environment. Note that while an event will be simulated and will appear when using endpoints such as [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) or [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) , no transactions will actually take place and funds will not move between accounts, even within the Sandbox. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a transfer. string Plaid’s unique identifier for a test clock. If provided, the event to be simulated is created at the `virtual_time` on the provided `test_clock`. required, string The asynchronous event to be simulated. May be: `posted`, `settled`, `failed`, `funds_available`, or `returned`. An error will be returned if the event type is incompatible with the current transfer status. Compatible status --> event type transitions include: `pending` --> `failed` `pending` --> `posted` `posted` --> `returned` `posted` --> `settled` `settled` --> `funds_available` (only applicable to ACH debits.) object The failure reason if the event type for a transfer is `"failed"` or `"returned"`. Null value otherwise. string The failure code, e.g. `R01`. A failure code will be provided if and only if the transfer status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . string A human-readable description of the reason for the failure or reversal. string The webhook URL to which a `TRANSFER_EVENTS_UPDATE` webhook should be sent. Format: `url` ```bash curl -X POST https://sandbox.plaid.com/sandbox/transfer/simulate \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "transfer_id": "123004561178933", "event_type": "posted" }' ``` ```node const request: SandboxTransferSimulateRequest = { transfer_id, event_type: 'posted', failure_reason: failureReason, }; try { const response = await plaidClient.sandboxTransferSimulate(request); // empty response upon success } catch (error) { // handle error } ``` ```python request = SandboxTransferSimulateRequest( transfer_id=transfer_id, event_type='posted', failure_reason='failed' ) response = client.sandbox_transfer_simulate(request) # empty response upon success ``` ```java SandboxTransferSimulateRequest request = new SandboxTransferSimulateRequest() .transferId(getTransfer().getId()) .eventType("posted"); Response simulateResponse = client() .sandboxTransferSimulate(request) .execute(); // empty response upon success ``` ```ruby request = Plaid::SandboxTransferSimulateRequest.new( { transfer_id: transfer_id, event_type: 'posted', failure_reason: 'failed' } ) response = client.sandbox_transfer_simulate(request) # empty response upon success ``` ```go request := plaid.NewTransferSimulateRequest("TRANSFER_ID", "posted") transferSimulateResp, _, err := client.PlaidApi.SandboxTransferSimulate(ctx).SandboxTransferSimulateRequest( *request, ).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/transfer/refund/simulate  #### Simulate a refund event in Sandbox  Use the [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) endpoint to simulate a refund event in the Sandbox environment. Note that while an event will be simulated and will appear when using endpoints such as [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) or [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) , no transactions will actually take place and funds will not move between accounts, even within the Sandbox. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a refund. string Plaid’s unique identifier for a test clock. If provided, the event to be simulated is created at the `virtual_time` on the provided `test_clock`. required, string The asynchronous event to be simulated. May be: `refund.posted`, `refund.settled`, `refund.failed`, or `refund.returned`. An error will be returned if the event type is incompatible with the current refund status. Compatible status --> event type transitions include: `refund.pending` --> `refund.failed` `refund.pending` --> `refund.posted` `refund.posted` --> `refund.returned` `refund.posted` --> `refund.settled` `refund.posted` events can only be simulated if the refunded transfer has been transitioned to settled. This mimics the ordering of events in Production. object The failure reason if the event type for a transfer is `"failed"` or `"returned"`. Null value otherwise. string The failure code, e.g. `R01`. A failure code will be provided if and only if the transfer status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . string A human-readable description of the reason for the failure or reversal. string The webhook URL to which a `TRANSFER_EVENTS_UPDATE` webhook should be sent. Format: `url` ```bash curl -X POST https://sandbox.plaid.com/sandbox/transfer/refund/simulate \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "refund_id": "123004561178933", "event_type": "refund.posted" }' ``` ```node const request: SandboxTransferRefundSimulateRequest = { refund_id: refundId, event_type: 'refund.posted', }; try { const response = await plaidClient.sandboxTransferRefundSimulate(request); // empty response upon success } catch (error) { // handle error } ``` ```python request = SandboxTransferRefundSimulateRequest( refund_id=refund_id, event_type='refund.posted' ) response = client.sandbox_transfer_refund_simulate(request) # empty response upon success ``` ```java SandboxTransferRefundSimulateRequest request = new SandboxTransferRefundSimulateRequest() .refundId(getRefund().getId()) .eventType("refund.posted"); Response response = client() .sandboxTransferRefundSimulate(request) .execute(); // empty response upon success ``` ```ruby request = Plaid::SandboxTransferRefundSimulateRequest.new( { refund_id: refund_id, event_type: 'refund.posted' } ) response = client.sandbox_transfer_refund_simulate(request) # empty response upon success ``` ```go request := plaid.NewTransferRefundSimulateRequest(refundID, "refund.posted") response, _, err := client.PlaidApi.SandboxTransferRefundSimulate(ctx).SandboxTransferRefundSimulateRequest( *request, ).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/transfer/ledger/deposit/simulate  #### Simulate a ledger deposit event in Sandbox  Use the [/sandbox/transfer/ledger/deposit/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerdepositsimulate) endpoint to simulate a ledger deposit event in the Sandbox environment. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a sweep. required, string The asynchronous event to be simulated. May be: `posted`, `settled`, `failed`, or `returned`. An error will be returned if the event type is incompatible with the current ledger sweep status. Compatible status --> event type transitions include: `sweep.pending` --> `sweep.posted` `sweep.pending` --> `sweep.failed` `sweep.posted` --> `sweep.settled` `sweep.posted` --> `sweep.returned` `sweep.settled` --> `sweep.returned` Possible values: `sweep.posted`, `sweep.settled`, `sweep.returned`, `sweep.failed` object The failure reason if the event type for a transfer is `"failed"` or `"returned"`. Null value otherwise. string The failure code, e.g. `R01`. A failure code will be provided if and only if the transfer status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . string A human-readable description of the reason for the failure or reversal. ```bash curl -X POST https://sandbox.plaid.com/sandbox/transfer/ledger/deposit/simulate \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "sweep_id": "f4ba7a287eae4d228d12331b68a9f35a", "event_type": "sweep.posted" }' ``` ```node const request: SandboxTransferLedgerDepositSimulateRequest = { sweep_id: 'f4ba7a287eae4d228d12331b68a9f35a', event_type: 'sweep.posted', }; try { const response = await plaidClient.sandboxTransferLedgerDepositSimulate( request, ); // empty response upon success } catch (error) { // handle error } ``` ```python request = SandboxTransferLedgerDepositSimulateRequest( transfer_id=transfer_id, event_type='sweep.posted' ) response = client.sandbox_transfer_ledger_deposit_simulate(request) # empty response upon success ``` ```java SandboxTransferLedgerDepositSimulateRequest request = new SandboxTransferLedgerDepositSimulateRequest() .sweepId("f4ba7a287eae4d228d12331b68a9f35a") .eventType("sweep.posted"); Response simulateResponse = client() .sandboxTransferLedgerDepositSimulate(request) .execute(); // empty response upon success ``` ```ruby request = Plaid::SandboxTransferLedgerDepositSimulateRequest.new( { transfer_id: transfer_id, event_type: 'sweep.posted' } ) response = client.sandbox_transfer_ledger_deposit_simulate(request) # empty response upon success ``` ```go request := plaid.NewTransferLedgerDepositSimulateRequest("SWEEP_ID", "sweep.posted") transferLedgerDepositSimulateResp, _, err := client.PlaidApi.SandboxTransferLedgerDepositSimulate(ctx).SandboxTransferLedgerDepositSimulateRequest( *request, ).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/transfer/ledger/simulate\_available  #### Simulate converting pending balance to available balance  Use the [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) endpoint to simulate converting pending balance to available balance for all originators in the Sandbox environment. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string Specify which ledger balance to simulate converting pending balance to available balance. If this field is left blank, this will default to id of the default ledger balance. string Client ID of the end customer (i.e. the originator). Only applicable to Transfer for Platforms customers. string Plaid’s unique identifier for a test clock. If provided, only the pending balance that is due before the `virtual_timestamp` on the test clock will be converted. string The webhook URL to which a `TRANSFER_EVENTS_UPDATE` webhook should be sent. Format: `url` ```bash curl -X POST https://sandbox.plaid.com/sandbox/transfer/ledger/simulate_available \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}" }' ``` ```node try { const response = await plaidClient.sandboxTransferLedgerSimulateAvailable({}); const available = response.data.balance.available; } catch (error) { // handle error } ``` ```python response = client.sandbox_transfer_ledger_simulate_available({}) balance = response['balance'] ``` ```java Response response = client().sandboxTransferLedgerSimulateAvailable(new Object()).execute(); Balance balance = response.body().getBalance(); ``` ```ruby response = client.sandbox_transfer_ledger_simulate_available({}) balance = response.balance ``` ```go resp, _, err := client.PlaidApi.SandboxTransferLedgerSimulateAvailable(ctx).Body(nil).Execute() if err != nil { plaidErr, _ := plaid.ToPlaidError(err) fmt.Println(plaidErr.ErrorMessage) } balance, ok := resp.GetBalance() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/transfer/ledger/withdraw/simulate  #### Simulate a ledger withdraw event in Sandbox  Use the [/sandbox/transfer/ledger/withdraw/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerwithdrawsimulate) endpoint to simulate a ledger withdraw event in the Sandbox environment. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a sweep. required, string The asynchronous event to be simulated. May be: `posted`, `settled`, `failed`, or `returned`. An error will be returned if the event type is incompatible with the current ledger sweep status. Compatible status --> event type transitions include: `sweep.pending` --> `sweep.posted` `sweep.pending` --> `sweep.failed` `sweep.posted` --> `sweep.settled` `sweep.posted` --> `sweep.returned` `sweep.settled` --> `sweep.returned` Possible values: `sweep.posted`, `sweep.settled`, `sweep.returned`, `sweep.failed` object The failure reason if the event type for a transfer is `"failed"` or `"returned"`. Null value otherwise. string The failure code, e.g. `R01`. A failure code will be provided if and only if the transfer status is `returned`. See [ACH return codes](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) for a full listing of ACH return codes and [RTP/RfP error codes](https://plaid.com/docs/errors/transfer/index.html.md#rtprfp-error-codes) for RTP error codes. deprecated, string The ACH return code, e.g. `R01`. A return code will be provided if and only if the transfer status is `returned`. For a full listing of ACH return codes, see [Transfer errors](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) . string A human-readable description of the reason for the failure or reversal. ```bash curl -X POST https://sandbox.plaid.com/sandbox/transfer/ledger/withdraw/simulate \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "sweep_id": "f4ba7a287eae4d228d12331b68a9f35a", "event_type": "sweep.posted" }' ``` ```node const request: SandboxTransferLedgerWithdrawSimulateRequest = { sweep_id: 'f4ba7a287eae4d228d12331b68a9f35a', event_type: 'sweep.posted', }; try { const response = await plaidClient.sandboxTransferLedgerWithdrawSimulate( request, ); // empty response upon success } catch (error) { // handle error } ``` ```python request = SandboxTransferLedgerWithdrawSimulateRequest( transfer_id=transfer_id, event_type='sweep.posted' ) response = client.sandbox_transfer_ledger_withdraw_simulate(request) # empty response upon success ``` ```java SandboxTransferLedgerWithdrawSimulateRequest request = new SandboxTransferLedgerWithdrawSimulateRequest() .sweepId("f4ba7a287eae4d228d12331b68a9f35a") .eventType("sweep.posted"); Response simulateResponse = client() .sandboxTransferLedgerWithdrawSimulate(request) .execute(); // empty response upon success ``` ```ruby request = Plaid::SandboxTransferLedgerWithdrawSimulateRequest.new( { transfer_id: transfer_id, event_type: 'sweep.posted' } ) response = client.sandbox_transfer_ledger_withdraw_simulate(request) # empty response upon success ``` ```go request := plaid.NewTransferLedgerWithdrawSimulateRequest("SWEEP_ID", "sweep.posted") transferLedgerWithdrawSimulateResp, _, err := client.PlaidApi.SandboxTransferLedgerWithdrawSimulate(ctx).SandboxTransferLedgerWithdrawSimulateRequest( *request, ).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/transfer/test\_clock/create  #### Create a test clock  Use the [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) endpoint to create a `test_clock` in the Sandbox environment. A test clock object represents an independent timeline and has a `virtual_time` field indicating the current timestamp of the timeline. Test clocks are used for testing recurring transfers in Sandbox. A test clock can be associated with up to 5 recurring transfers. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The virtual timestamp on the test clock. If not provided, the current timestamp will be used. This will be of the form `2006-01-02T15:04:05Z`. Format: `date-time` ```bash curl -X POST https://sandbox.plaid.com/sandbox/transfer/test_clock/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "virtual_time": "2006-01-02T15:04:05Z" }' ``` ```node const request: SandboxTransferTestClockCreateRequest = { virtual_time: '2006-01-02T15:04:05Z', }; try { const response = await plaidClient.sandboxTransferTestClockCreate(request); const test_clock = response.data.test_clock; } catch (error) { // handle error } ``` ```python request = SandboxTransferTestClockCreateRequest( virtual_time='2006-01-02T15:04:05Z' ) response = client.sandbox_transfer_test_clock_create(request) test_clock = response['test_clock'] ``` ```java SandboxTransferTestClockCreateRequest request = new SandboxTransferTestClockCreateRequest() .virtualTime("2006-01-02T15:04:05Z"); Response testClockCreateResponse = client() .sandboxTransferTestClockCreate(request) .execute(); TestClock testClock = testClockCreateResponse.body().getTestClock(); ``` ```ruby request = Plaid::SandboxTransferTestClockCreateRequest.new( { virtual_time: '2006-01-02T15:04:05Z', } ) response = client.sandbox_transfer_test_clock_create(request) test_clock = response.test_clock ``` ```go layout := "2006-01-02T15:04:05.000Z" virtualTime, _ := time.Parse(layout, "2006-01-02T15:04:05Z") request := plaid.NewSandboxTransferTestClockCreateRequest(); request.SetVirtualTime(virtualTime); resp, _, err := client.PlaidApi.SandboxTransferTestClockCreate(ctx).SandboxTransferTestClockCreateRequest(*request).Execute() if err != nil { plaidErr, _ := plaid.ToPlaidError(err) fmt.Println(plaidErr.ErrorMessage) } testClock, ok := resp.GetTestClock() if ok { fmt.Printf("created test_clock %v\n", testClock) } ``` #### Response fields  object Defines the test clock for a transfer. string Plaid’s unique identifier for a test clock. This field is only populated in the Sandbox environment, and only if a `test_clock_id` was included in the `/transfer/recurring/create` request. For more details, see [Simulating recurring transfers](https://plaid.com/docs/transfer/sandbox/index.html.md#simulating-recurring-transfers) . string The virtual timestamp on the test clock. This will be of the form `2006-01-02T15:04:05Z`. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "test_clock": { "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c", "virtual_time": "2006-01-02T15:04:05Z" }, "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/transfer/test\_clock/advance  #### Advance a test clock  Use the [/sandbox/transfer/test\_clock/advance](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockadvance) endpoint to advance a `test_clock` in the Sandbox environment. A test clock object represents an independent timeline and has a `virtual_time` field indicating the current timestamp of the timeline. A test clock can be advanced by incrementing `virtual_time`, but may never go back to a lower `virtual_time`. If a test clock is advanced, we will simulate the changes that ought to occur during the time that elapsed. For example, a client creates a weekly recurring transfer with a test clock set at t. When the client advances the test clock by setting `virtual_time` = t + 15 days, 2 new originations should be created, along with the webhook events. The advancement of the test clock from its current `virtual_time` should be limited such that there are no more than 20 originations resulting from the advance operation on each `recurring_transfer` associated with the `test_clock`. For example, if the recurring transfer associated with this test clock originates once every 4 weeks, you can advance the `virtual_time` up to 80 weeks on each API call. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a test clock. This field is only populated in the Sandbox environment, and only if a `test_clock_id` was included in the `/transfer/recurring/create` request. For more details, see [Simulating recurring transfers](https://plaid.com/docs/transfer/sandbox/index.html.md#simulating-recurring-transfers) . required, string The virtual timestamp on the test clock. This will be of the form `2006-01-02T15:04:05Z`. Format: `date-time` ```bash curl -X POST https://sandbox.plaid.com/sandbox/transfer/test_clock/advance \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c", "new_virtual_time": "2006-01-02T15:04:05Z" }' ``` ```node const request: SandboxTransferTestClockAdvanceRequest = { test_clock_id: 'b33a6eda-5e97-5d64-244a-a9274110151c', new_virtual_time: '2006-01-02T15:04:05Z', }; try { const response = await plaidClient.sandboxTransferTestClockAdvance(request); } catch (error) { // handle error } ``` ```python request = SandboxTransferTestClockAdvanceRequest( test_clock_id='b33a6eda-5e97-5d64-244a-a9274110151c', new_virtual_time='2006-01-02T15:04:05Z' ) response = client.sandbox_transfer_test_clock_advance(request) ``` ```java SandboxTransferTestClockAdvanceRequest request = new SandboxTransferTestClockAdvanceRequest() .testClockId("b33a6eda-5e97-5d64-244a-a9274110151c") .newVirtualTime("2006-01-02T15:04:05Z"); Response testClockAdvanceResponse = client() .sandboxTransferTestClockAdvance(request) .execute(); ``` ```ruby request = Plaid::SandboxTransferTestClockAdvanceRequest.new( { test_clock_id: 'b33a6eda-5e97-5d64-244a-a9274110151c', new_virtual_time: '2006-01-02T15:04:05Z' } ) response = client.sandbox_transfer_test_clock_advance(request) ``` ```go layout := "2006-01-02T15:04:05.000Z" newVirtualTime, _ := time.Parse(layout, "2006-01-02T15:04:05Z") request := plaid.NewSandboxTransferTestClockAdvanceRequest("b33a6eda-5e97-5d64-244a-a9274110151c", newVirtualTime) resp, _, err := client.PlaidApi.SandboxTransferTestClockAdvance(ctx).SandboxTransferTestClockAdvanceRequest(*request).Execute() if err != nil { plaidErr, _ := plaid.ToPlaidError(err) fmt.Println(plaidErr.ErrorMessage) } ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/transfer/test\_clock/get  #### Get a test clock  Use the [/sandbox/transfer/test\_clock/get](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockget) endpoint to get a `test_clock` in the Sandbox environment. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string Plaid’s unique identifier for a test clock. This field is only populated in the Sandbox environment, and only if a `test_clock_id` was included in the `/transfer/recurring/create` request. For more details, see [Simulating recurring transfers](https://plaid.com/docs/transfer/sandbox/index.html.md#simulating-recurring-transfers) . ```bash curl -X POST https://sandbox.plaid.com/sandbox/transfer/test_clock/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c" }' ``` ```node const request: SandboxTransferTestClockGetRequest = { test_clock_id: 'b33a6eda-5e97-5d64-244a-a9274110151c', }; try { const response = await plaidClient.sandboxTransferTestClockGet(request); const test_clock = response.data.test_clock; } catch (error) { // handle error } ``` ```python request = SandboxTransferTestClockGetRequest( test_clock_id='b33a6eda-5e97-5d64-244a-a9274110151c' ) response = client.sandbox_transfer_test_clock_get(request) test_clock = response['test_clock'] ``` ```java SandboxTransferTestClockGetRequest request = new SandboxTransferTestClockGetRequest() .testClockId("b33a6eda-5e97-5d64-244a-a9274110151c"); Response testClockGetResponse = client() .sandboxTransferTestClockGet(request) .execute(); TestClock testClock = testClockGetResponse.body().getTestClock(); ``` ```ruby request = Plaid::SandboxTransferTestClockGetRequest.new( { test_clock_id: 'b33a6eda-5e97-5d64-244a-a9274110151c' } ) response = client.sandbox_transfer_test_clock_get(request) test_clock = response.test_clock ``` ```go request := plaid.NewSandboxTransferTestClockGetRequest("b33a6eda-5e97-5d64-244a-a9274110151c") resp, _, err := client.PlaidApi.SandboxTransferTestClockGet(ctx).SandboxTransferTestClockGetRequest(*request).Execute() if err != nil { plaidErr, _ := plaid.ToPlaidError(err) fmt.Println(plaidErr.ErrorMessage) } testClock, ok := resp.GetTestClock() ``` #### Response fields  object Defines the test clock for a transfer. string Plaid’s unique identifier for a test clock. This field is only populated in the Sandbox environment, and only if a `test_clock_id` was included in the `/transfer/recurring/create` request. For more details, see [Simulating recurring transfers](https://plaid.com/docs/transfer/sandbox/index.html.md#simulating-recurring-transfers) . string The virtual timestamp on the test clock. This will be of the form `2006-01-02T15:04:05Z`. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "test_clock": { "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c", "virtual_time": "2006-01-02T15:04:05Z" }, "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/transfer/test\_clock/list  #### List test clocks  Use the [/sandbox/transfer/test\_clock/list](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clocklist) endpoint to see a list of all your test clocks in the Sandbox environment, by ascending `virtual_time`. Results are paginated; use the `count` and `offset` query parameters to retrieve the desired test clocks. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The start virtual timestamp of test clocks to return. This should be in RFC 3339 format (i.e. `2019-12-06T22:35:49Z`) Format: `date-time` string The end virtual timestamp of test clocks to return. This should be in RFC 3339 format (i.e. `2019-12-06T22:35:49Z`) Format: `date-time` integer The maximum number of test clocks to return. Minimum: `1` Maximum: `25` Default: `25` integer The number of test clocks to skip before returning results. Default: `0` Minimum: `0` ```bash curl -X POST https://sandbox.plaid.com/sandbox/transfer/test_clock/list \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "count": 2 }' ``` ```node const request: SandboxTransferTestClockListRequest = { count: 2, }; try { const response = await plaidClient.sandboxTransferTestClockList(request); const test_clocks = response.data.test_clocks; } catch (error) { // handle error } ``` ```python request = SandboxTransferTestClockListRequest( count=2 ) response = client.sandbox_transfer_test_clock_list(request) test_clocks = response['test_clocks'] ``` ```java SandboxTransferTestClockListRequest request = new SandboxTransferTestClockListRequest() .count(1); Response testClockListResponse = client() .sandboxTransferTestClockList(request) .execute(); List testClocks = testClockListResponse.body().getTestClocks(); ``` ```ruby request = Plaid::SandboxTransferTestClockListRequest.new( { count: 2 } ) response = client.sandbox_transfer_test_clock_list(request) test_clocks = response.test_clocks ``` ```go request := plaid.NewSandboxTransferTestClockListRequest() request.SetCount(2) resp, _, err := client.PlaidApi.SandboxTransferTestClockList(ctx).SandboxTransferTestClockListRequest(*request).Execute() if err != nil { plaidErr, _ := plaid.ToPlaidError(err) fmt.Println(plaidErr.ErrorMessage) } testClocks, ok := resp.GetTestClocks() ``` #### Response fields  \[object\] string Plaid’s unique identifier for a test clock. This field is only populated in the Sandbox environment, and only if a `test_clock_id` was included in the `/transfer/recurring/create` request. For more details, see [Simulating recurring transfers](https://plaid.com/docs/transfer/sandbox/index.html.md#simulating-recurring-transfers) . string The virtual timestamp on the test clock. This will be of the form `2006-01-02T15:04:05Z`. Format: `date-time` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "test_clocks": [ { "test_clock_id": "b33a6eda-5e97-5d64-244a-a9274110151c", "virtual_time": "2006-01-02T15:04:05Z" }, { "test_clock_id": "a33a6eda-5e97-5d64-244a-a9274110152d", "virtual_time": "2006-02-02T15:04:05Z" } ], "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/income/fire\_webhook  #### Manually fire an Income webhook  Use the [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) endpoint to manually trigger a Payroll or Document Income webhook in the Sandbox environment. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The Item ID associated with the verification. string The Plaid `user_id` of the User associated with this webhook, warning, or error. required, string The URL to which the webhook should be sent. Format: `url` string `VERIFICATION_STATUS_PROCESSING_COMPLETE`: The income verification status processing has completed. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the `/income/verification/paystubs/get` endpoint and check the document metadata to see which documents were successfully parsed. `VERIFICATION_STATUS_PROCESSING_FAILED`: A failure occurred when attempting to process the verification documentation. `VERIFICATION_STATUS_PENDING_APPROVAL`: (deprecated) The income verification has been sent to the user for review. Possible values: `VERIFICATION_STATUS_PROCESSING_COMPLETE`, `VERIFICATION_STATUS_PROCESSING_FAILED`, `VERIFICATION_STATUS_PENDING_APPROVAL` required, string The webhook codes that can be fired by this test endpoint. Possible values: `INCOME_VERIFICATION`, `INCOME_VERIFICATION_RISK_SIGNALS` ```bash curl -X POST https://sandbox.plaid.com/sandbox/income/fire_webhook \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "item_id": "Rn3637v1adCNj5Dl1LG6idQBzqBLwRcRZLbgM", "webhook": "https://webhook.com/", "verification_status": "VERIFICATION_STATUS_PROCESSING_COMPLETE" }' ``` ```node const request: SandboxIncomeFireWebhookRequest = { item_id: 'Rn3637v1adCNj5Dl1LG6idQBzqBLwRcRZLbgM', webhook: 'https://webhook.com/', verification_status: 'VERIFICATION_STATUS_PROCESSING_COMPLETE', }; try { const response = await plaidClient.sandboxIncomeFireWebhook(request); // empty response upon success } catch (error) { // handle error } ``` ```python request = SandboxIncomeWebhookRequest( item_id='Rn3637v1adCNj5Dl1LG6idQBzqBLwRcRZLbgM', webhook='https://www.webhook.com', verification_status='VERIFICATION_STATUS_PROCESSING_COMPLETE' ) response = client.sandbox_income_fire_webhook(request) # empty response upon success ``` ```java SandboxIncomeFireWebhookRequest request = new SandboxIncomeFireWebhookRequest() .itemId("Rn3637v1adCNj5Dl1LG6idQBzqBLwRcRZLbgM") .webhook("https://www.webhook.com") .verificationStatus("VERIFICATION_STATUS_PROCESSING_COMPLETE"); Response response = client() .sandboxIncomeFireWebhook(request) .execute(); ``` ```ruby request = Plaid::SandboxIncomeFireWebhookRequest.new( { item_id: 'Rn3637v1adCNj5Dl1LG6idQBzqBLwRcRZLbgM', webhook: 'https://www.webhook.com', verification_status: 'VERIFICATION_STATUS_PROCESSING_COMPLETE' } ) response = client.sandbox_income_fire_webhook(request) # empty response upon success ``` ```go request := plaid.NewSandboxIncomeFireWebhookRequest("Rn3637v1adCNj5Dl1LG6idQBzqBLwRcRZLbgM", "https://www.webhook.com", "VERIFICATION_STATUS_PROCESSING_COMPLETE") incomeFireWebhookResp, _, err := client.PlaidApi.SandboxIncomeFireWebhook(ctx).SandboxIncomeFireWebhookRequest( *request, ).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/cra/cashflow\_updates/update  #### Trigger an update for Cash Flow Updates  Use the [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) endpoint to manually trigger an update for Cash Flow Updates (Monitoring) in the Sandbox environment. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . \[string\] Webhook codes corresponding to the Cash Flow Updates events to be simulated. Possible values: `LARGE_DEPOSIT_DETECTED`, `LOW_BALANCE_DETECTED`, `NEW_LOAN_PAYMENT_DETECTED`, `NSF_OVERDRAFT_DETECTED` string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/sandbox/cra/cashflow_updates/update \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw", "webhook_codes": ["LARGE_DEPOSIT_DETECTED", "LOW_BALANCE_DETECTED"] }' ``` ```node const request: SandboxCraCashflowUpdatesUpdateRequest = { user_id: 'usr_9nSp2KuZ2x4JDw', webhook_codes: ['LARGE_DEPOSIT_DETECTED', 'LOW_BALANCE_DETECTED'], }; try { const response = await plaidClient.sandboxCraCashflowUpdatesUpdate(request); // empty response upon success } catch (error) { // handle error } ``` ```python request = SandboxCraCashflowUpdatesUpdateRequest( user_id='usr_9nSp2KuZ2x4JDw', webhook_codes=['LARGE_DEPOSIT_DETECTED', 'LOW_BALANCE_DETECTED'] ) response = client.sandbox_cra_cashflow_updates_update(request) # empty response upon success ``` ```java SandboxCraCashflowUpdatesUpdateRequest request = new SandboxCraCashflowUpdatesUpdateRequest() .userId("usr_9nSp2KuZ2x4JDw") .webhookCodes(Arrays.asList("LARGE_DEPOSIT_DETECTED", "LOW_BALANCE_DETECTED")); Response response = client() .sandboxCraCashflowUpdatesUpdate(request) .execute(); ``` ```ruby request = Plaid::SandboxCraCashflowUpdatesUpdateRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw', webhook_codes: ['LARGE_DEPOSIT_DETECTED', 'LOW_BALANCE_DETECTED'] } ) response = client.sandbox_cra_cashflow_updates_update(request) # empty response upon success ``` ```go request := plaid.NewSandboxCraCashflowUpdatesUpdate() request.SetUserId("usr_9nSp2KuZ2x4JDw") request.SetWebhookCodes([]string{"LARGE_DEPOSIT_DETECTED", "LOW_BALANCE_DETECTED"}) craCashflowUpdatesResp, _, err := client.PlaidApi.SandboxCraCashflowUpdatesUpdate(ctx).SandboxCraCashflowUpdatesUpdateRequest( *request, ).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "mdqfuVxeoza6mhu" } ``` \=\*=\*=\*= #### /sandbox/payment/simulate  #### Simulate a payment event in Sandbox  Use the [/sandbox/payment/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpaymentsimulate) endpoint to simulate various payment events in the Sandbox environment. This endpoint will trigger the corresponding payment status webhook. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The ID of the payment to simulate required, string The webhook url to use for any payment events triggered by the simulated status change. required, string The status to set the payment to. Valid statuses include: * `PAYMENT_STATUS_INITIATED` * `PAYMENT_STATUS_INSUFFICIENT_FUNDS` * `PAYMENT_STATUS_FAILED` * `PAYMENT_STATUS_EXECUTED` * `PAYMENT_STATUS_SETTLED` * `PAYMENT_STATUS_CANCELLED` * `PAYMENT_STATUS_REJECTED` ```bash curl -X POST https://sandbox.plaid.com/sandbox/payment/simulate/ \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3", "status": "PAYMENT_STATUS_INITIATED" }' ``` ```node const request: SandboxPaymentSimulateRequest = { payment_id: 'payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3', status: "PAYMENT_STATUS_INITIATED" }; try { const response = await plaidClient.sandboxPaymentSimulate(request); } catch (error) { // handle error } ``` ```python request = SandboxPaymentSimulateRequest( payment_id='payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3', status="PAYMENT_STATUS_INITIATED" ) response = client.sandbox_payment_simulate(request) ``` ```java SandboxPaymentSimulateRequest request = new SandboxPaymentSimulateRequest() .paymentId("payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3") .status("PAYMENT_STATUS_INITIATED"); Response response = client() .sandboxPaymentSimulate(request) .execute(); ``` ```ruby request = Plaid::SandboxPaymentSimulateRequest.new({ payment_id: "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3", status: "PAYMENT_STATUS_INITIATED" }) response = client.sandbox_payment_simulate(request) ``` ```go request := plaid.NewSandboxPaymentSimulateRequest("payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3", "PAYMENT_STATUS_INITIATED") response, _, err := client.PlaidApi.SandboxPaymentSimulate(ctx).SandboxPaymentSimulateRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. string The status of the payment. Core lifecycle statuses: **`PAYMENT_STATUS_INPUT_NEEDED`**: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. **`PAYMENT_STATUS_AUTHORISING`:** Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. **`PAYMENT_STATUS_INITIATED`:** The payment has been authorised and accepted by the financial institution. In many EU markets, `PAYMENT_STATUS_EXECUTED` is not supported, and a payment will remain in `PAYMENT_STATUS_INITIATED` until the funds settle, making this a terminal success state in those cases. A payment in `PAYMENT_STATUS_INITIATED` should be treated as a successfully submitted payment; do not gate downstream processing on reaching `PAYMENT_STATUS_EXECUTED`. For a full explanation of payment statuses and how to handle each, see the [Payment Status guide](https://plaid.com/docs/payment-initiation/payment-status/index.html.md) . **`PAYMENT_STATUS_EXECUTED`: Terminal.** The funds have left the payer’s account and the payment is en route to settlement. Note that this status does not confirm that funds have arrived in the recipient’s account; do not use it as proof of fund receipt. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in `PAYMENT_STATUS_INITIATED` before settling. When using Plaid Virtual Accounts, `PAYMENT_STATUS_EXECUTED` is not terminal—the payment will continue to `PAYMENT_STATUS_SETTLED` once funds are available. **`PAYMENT_STATUS_SETTLED`: Terminal.** The funds are available in the recipient’s account. Only available to customers using [Plaid Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) . Failure statuses: **`PAYMENT_STATUS_INSUFFICIENT_FUNDS`: Terminal.** The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. **`PAYMENT_STATUS_FAILED`: Terminal (retryable).** The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. **`PAYMENT_STATUS_BLOCKED`: Terminal (retryable).** The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. **`PAYMENT_STATUS_REJECTED`: Terminal.** The payment was rejected by the financial institution. No automatic retry is possible. **`PAYMENT_STATUS_CANCELLED`: Terminal.** The end user cancelled the payment during authorisation. Standing-order statuses: **`PAYMENT_STATUS_ESTABLISHED`: Terminal.** A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): `PAYMENT_STATUS_UNKNOWN`: The payment status is unknown. `PAYMENT_STATUS_PROCESSING`: The payment is currently being processed. `PAYMENT_STATUS_COMPLETED`: Indicates that the standing order has been successfully established. Possible values: `PAYMENT_STATUS_INPUT_NEEDED`, `PAYMENT_STATUS_PROCESSING`, `PAYMENT_STATUS_INITIATED`, `PAYMENT_STATUS_COMPLETED`, `PAYMENT_STATUS_INSUFFICIENT_FUNDS`, `PAYMENT_STATUS_FAILED`, `PAYMENT_STATUS_BLOCKED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_STATUS_EXECUTED`, `PAYMENT_STATUS_SETTLED`, `PAYMENT_STATUS_AUTHORISING`, `PAYMENT_STATUS_CANCELLED`, `PAYMENT_STATUS_ESTABLISHED`, `PAYMENT_STATUS_REJECTED` string The status of the payment. Core lifecycle statuses: **`PAYMENT_STATUS_INPUT_NEEDED`**: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. **`PAYMENT_STATUS_AUTHORISING`:** Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. **`PAYMENT_STATUS_INITIATED`:** The payment has been authorised and accepted by the financial institution. In many EU markets, `PAYMENT_STATUS_EXECUTED` is not supported, and a payment will remain in `PAYMENT_STATUS_INITIATED` until the funds settle, making this a terminal success state in those cases. A payment in `PAYMENT_STATUS_INITIATED` should be treated as a successfully submitted payment; do not gate downstream processing on reaching `PAYMENT_STATUS_EXECUTED`. For a full explanation of payment statuses and how to handle each, see the [Payment Status guide](https://plaid.com/docs/payment-initiation/payment-status/index.html.md) . **`PAYMENT_STATUS_EXECUTED`: Terminal.** The funds have left the payer’s account and the payment is en route to settlement. Note that this status does not confirm that funds have arrived in the recipient’s account; do not use it as proof of fund receipt. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in `PAYMENT_STATUS_INITIATED` before settling. When using Plaid Virtual Accounts, `PAYMENT_STATUS_EXECUTED` is not terminal—the payment will continue to `PAYMENT_STATUS_SETTLED` once funds are available. **`PAYMENT_STATUS_SETTLED`: Terminal.** The funds are available in the recipient’s account. Only available to customers using [Plaid Virtual Accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) . Failure statuses: **`PAYMENT_STATUS_INSUFFICIENT_FUNDS`: Terminal.** The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. **`PAYMENT_STATUS_FAILED`: Terminal (retryable).** The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. **`PAYMENT_STATUS_BLOCKED`: Terminal (retryable).** The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. **`PAYMENT_STATUS_REJECTED`: Terminal.** The payment was rejected by the financial institution. No automatic retry is possible. **`PAYMENT_STATUS_CANCELLED`: Terminal.** The end user cancelled the payment during authorisation. Standing-order statuses: **`PAYMENT_STATUS_ESTABLISHED`: Terminal.** A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): `PAYMENT_STATUS_UNKNOWN`: The payment status is unknown. `PAYMENT_STATUS_PROCESSING`: The payment is currently being processed. `PAYMENT_STATUS_COMPLETED`: Indicates that the standing order has been successfully established. Possible values: `PAYMENT_STATUS_INPUT_NEEDED`, `PAYMENT_STATUS_PROCESSING`, `PAYMENT_STATUS_INITIATED`, `PAYMENT_STATUS_COMPLETED`, `PAYMENT_STATUS_INSUFFICIENT_FUNDS`, `PAYMENT_STATUS_FAILED`, `PAYMENT_STATUS_BLOCKED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_STATUS_EXECUTED`, `PAYMENT_STATUS_SETTLED`, `PAYMENT_STATUS_AUTHORISING`, `PAYMENT_STATUS_CANCELLED`, `PAYMENT_STATUS_ESTABLISHED`, `PAYMENT_STATUS_REJECTED` Response Object ```json { "request_id": "m8MDnv9okwxFNBV", "old_status": "PAYMENT_STATUS_INPUT_NEEDED", "new_status": "PAYMENT_STATUS_INITIATED" } ``` \=\*=\*=\*= #### /sandbox/transactions/create  #### Create sandbox transactions  Use the [/sandbox/transactions/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransactionscreate) endpoint to create new transactions for an existing Item. This endpoint can be used to add up to 10 transactions to any Item at a time. This endpoint can only be used with Items that were created in the Sandbox environment using the `user_transactions_dynamic` test user. You can use this to add transactions to test the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) and [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoints. Custom transactions are only applied to the depository account. Support for per-account targeting may be added in the future. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The access token associated with the Item data is being requested for. required, \[object\] List of transactions to be added required, string The date of the transaction, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format. Transaction date must be the present date or a date up to 14 days in the past. Future dates are not allowed. Format: `date` required, string The date the transaction posted, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) (YYYY-MM-DD) format. Posted date must be the present date or a date up to 14 days in the past. Future dates are not allowed. Format: `date` required, number The transaction amount. Can be negative. Format: `double` required, string The transaction description. string The ISO-4217 format currency code for the transaction. Defaults to USD. ```bash curl -X POST https://sandbox.plaid.com/sandbox/transactions/create \ -H 'content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "transactions": [ { "amount": 100.50, "date_posted": "2025-06-08", "date_transacted": "2025-06-08", "description": "Tim Hortons" }, { "amount": -25.75, "date_posted": "2025-06-08", "date_transacted": "2025-06-08", "description": "BestBuy", "iso_currency_code": "CAD" } ] }' ``` ```node const request: SandboxTransactionsCreateRequest = { access_token: accessToken, transactions: [ { amount: 100.50, date_posted: '2025-06-08', date_transacted: '2025-06-08', description: 'Tim Hortons' }, { amount: -25.75, date_posted: '2025-06-08', date_transacted: '2025-06-08', description: 'BestBuy', iso_currency_code: 'CAD' } ] }; try { const response = await plaidClient.sandboxTransactionsCreate(request); } catch (error) { // handle error } ``` ```ruby request = Plaid::SandboxTransactionsCreateRequest.new({ access_token: access_token, transactions: [ { amount: 100.50, date_posted: '2025-06-08', date_transacted: '2025-06-08', description: 'Tim Hortons' }, { amount: -25.75, date_posted: '2025-06-08', date_transacted: '2025-06-08', description: 'BestBuy', iso_currency_code: 'CAD' } ] }) response = client.sandbox_transactions_create(request) ``` ```java List transactions = Arrays.asList( new SandboxTransaction() .amount(100.50) .datePosted("2025-06-08") .dateTransacted("2025-06-08") .description("Tim Hortons"), new SandboxTransaction() .amount(-25.75) .datePosted("2025-06-08") .dateTransacted("2025-06-08") .description("BestBuy") .isoCurrencyCode("CAD") ); SandboxTransactionsCreateRequest request = new SandboxTransactionsCreateRequest() .accessToken(accessToken) .transactions(transactions); Response response = client() .sandboxTransactionsCreate(request) .execute(); ``` ```python request = SandboxTransactionsCreateRequest( access_token=access_token, transactions=[ { 'amount': 100.50, 'date_posted': '2025-06-08', 'date_transacted': '2025-06-08', 'description': 'Tim Hortons' }, { 'amount': -25.75, 'date_posted': '2025-06-08', 'date_transacted': '2025-06-08', 'description': 'BestBuy', 'iso_currency_code': 'CAD' } ] ) response = client.sandbox_transactions_create(request) ``` ```go transactions := []plaid.SandboxTransaction{ { Amount: 100.50, DatePosted: "2025-06-08", DateTransacted: "2025-06-08", Description: "Tim Hortons", }, { Amount: -25.75, DatePosted: "2025-06-08", DateTransacted: "2025-06-08", Description: "BestBuy", IsoCurrencyCode: "CAD", }, } request := plaid.NewSandboxTransactionsCreateRequest(accessToken, transactions) response, _, err := client.PlaidApi.SandboxTransactionsCreate(ctx).SandboxTransactionsCreateRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "m8MDnv9okwxFNBV" } ``` --- # API - Users | Plaid Docs User endpoints  =============== #### API reference for user management endpoints  This page covers API endpoints related to user ids and user tokens, which are used by [Plaid Check](https://plaid.com/docs/check/index.html.md) , Plaid Protect, and [Income](https://plaid.com/docs/income/index.html.md) , as well as by the [Multi-Item Link flow](https://plaid.com/docs/link/multi-item-link/index.html.md) . | Guides | | | --- | --- | | [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) | Overview of changes introduced in the new User APIs | | [Migrate to new User APIs](https://plaid.com/docs/api/users/migrate-to-new-user-apis/index.html.md) | Migration guide for existing Consumer Report integrations on legacy User APIs | | Endpoints | | | --- | --- | | [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) | Create a user ID | | [/user/get](https://plaid.com/docs/api/users/index.html.md#userget) | Get user details | | [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) | Update user data or enable an existing user for Plaid Check | | [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) | Remove the user and their associated Items | | [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) | Return Items associated with a user | | [/user/items/remove](https://plaid.com/docs/api/users/index.html.md#useritemsremove) | Remove Items associated with a User | | See also | | | --- | --- | | [/sandbox/user/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxuserreset_login) | Force user into an error state for testing | Plaid has switched from using the `user_token` to the `user_id` as of December 10, 2025. If you have an existing integration that uses the `user_token`, you should continue to use the `user_token`. New customers must use the `user_id`. To accommodate both flows, many Plaid API endpoints use either a `user_id` or a `user_token`. In these API requests, you should provide a `user_token` only if you have one; otherwise, provide a `user_id`. You do not need to provide both fields. For more details on this change, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . #### User identifiers  There are three identifiers Plaid uses when working with users: `client_user_id`: The unique identifier you provide to Plaid for each end user in your application. This is determined by you and will typically correspond to your application's primary key for a user record. It must not contain PII, such as a phone number, Social Security number, or email address. `user_id`: Plaid-generated identifier, prefixed by `usr_` and returned in responses from the User APIs and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Each `user_id` corresponds to a single `client_user_id`; calling [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) repeatedly with the same `client_user_id` returns the same `user_id`. The `user_id` is used by customers who integrated on December 10, 2025 or later. `user_token` — A Plaid-generated token for accessing the user. Only applicable for customers who integrated with [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) prior to December 10, 2025. Note that `user_tokens` can also have corresponding `user_id`s; these are not equivalent to the new `usr_` `user_id`s mentioned above. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . \=\*=\*=\*= #### /user/create  #### Create user  For Plaid products and flows that use the user object, [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) provides you a single token to access all data associated with the user. You must call this endpoint before calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) if you are using any of the following: Plaid Check, Income Verification, Multi-Item Link, or Plaid Protect (Identity). If you are using Plaid Protect Link session scoring, you do not need to call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) first; Plaid will resolve or create the user when `user.client_user_id` is provided in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . For customers who began using this endpoint on or after December 10, 2025, this endpoint takes a `client_user_id` and an `identity` object and will return a `user_id`. For customers who began using it before that date, the endpoint takes a `client_user_id` and a `consumer_report_user_identity` object and will return a `user_token` and `user_id`. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . In order to create a Plaid Check Consumer Report for a user, the `identity` (new) or `consumer_report_user_identity` (legacy) object must be present. If it is not provided during the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) call, it can be added later by calling [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) . In order to generate a Plaid Check Consumer Report, the following `identity` fields, at minimum, are required and must be non-empty: `name`, `date_of_birth`, `emails`, `phone_numbers`, and `addresses`, (with at least one email, phone number, and address designated as `primary`). Plaid Check Consumer Reports can only be created for US-based users; the user's address country must be `US`. If creating a report for sharing with a GSE such as Fannie or Freddie, the user's full SSN must be provided via the `id_numbers` field. Providing at least a partial SSN is also strongly recommended for all use cases, since it improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. When using Plaid Protect, it is highly recommended that you provide an `identity` object to better identify and block fraud across your Link sessions. Plaid will normalize identity fields before storing them and utilize the same identity across different user-based products. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string A unique ID representing the end user. Maximum of 128 characters. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the `client_user_id`. Max length: `128` Min length: `1` object The identity fields associated with a user. For a user to be eligible for a Plaid Check Consumer Report, all fields are required except `id_number`. Providing a partial SSN is strongly recommended, and improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. If creating a report that will be shared with GSEs such as Fannie or Freddie, a full Social Security Number must be provided via the `id_number` field. object User name information. required, string User's given name. required, string User's family name. string The user's date of birth, to be provided in the format "yyyy-mm-dd". Format: `date` \[object\] The user's emails. required, string User's email. required, boolean Indicates whether this is the primary email for the User. \[object\] The user's phone numbers, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. required, string User's phone number. required, boolean Indicates whether this is the primary phone number for the User. \[object\] The user's addresses. string First line of street address. string Second line of street address. string City name. string State, province or region. required, string Country code. string Postal or ZIP code. required, boolean Indicates whether this is the primary address for the User. \[object\] The user's ID numbers. required, string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . required, string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` object This field is only used by integrations created before December 10, 2025. All other integrations must use the `identity` object instead. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . To create a Plaid Check Consumer Report for a user when using a `user_token`, this field must be present. If this field is not provided during user token creation, you can add it to the user later by calling `/user/update`. Once the field has been added to the user, you will be able to call `/link/token/create` with a non-empty `consumer_report_permissible_purpose` (which will automatically create a Plaid Check Consumer Report), or call `/cra/check_report/create` for that user. required, string The user's first name required, string The user's last name required, \[string\] The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. required, \[string\] The user's emails string The user's full social security number. This field should only be provided by lenders intending to share the resulting consumer report with a Government-Sponsored Enterprise (GSE), such as Fannie Mae or Freddie Mac. Format: "ddd-dd-dddd" string The last 4 digits of the user's social security number. Max length: `4` Min length: `4` required, string To be provided in the format "yyyy-mm-dd". This field is required for all Plaid Check customers. Format: `date` required, object Data about the components comprising an address. required, string The full city name required, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` required, string The full street address Example: `"564 Main Street, APT 15"` required, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. required, string The ISO 3166-1 alpha-2 country code boolean If your integration with the User API predates December 10, 2025, set this field to `true` to opt into the [new User API](https://plaid.com/docs/api/users/user-apis/index.html.md) . When enabled, you can use the `identity` field instead of `consumer_report_user_identity`. ```bash curl -X POST https://sandbox.plaid.com/user/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_user_id": "c0e2c4ee-b763-4af5-cfe9-46a46bce883d", "identity": { "name": { "given_name": "Carmen", "family_name": "Berzatto" }, "date_of_birth": "1987-01-31", "emails": [ { "data": "carmen@example.com", "primary": true } ], "phone_numbers": [ { "data": "+13125551212", "primary": true }, { "data": "+12125551212", "primary": false } ], "addresses": [ { "street_1": "3200 W Armitage Ave", "street_2": null, "city": "Chicago", "region": "IL", "country": "US", "postal_code": "60657", "primary": true } ], "id_numbers": [ { "value": "1234", "type": "us_ssn_last_4" } ] } }' ``` ```node const request = { client_user_id: "c0e2c4ee-b763-4af5-cfe9-46a46bce883d", identity: { name: { given_name: "Carmen", family_name: "Berzatto" }, date_of_birth: "1987-01-31", emails: [ { data: "carmy@example.com", primary: true }, { data: "bear@example.com", primary: false } ], phone_numbers: [ { data: "+13125551212", primary: true } ], addresses: [ { street_1: "3200 W Armitage Ave", street_2: null, city: "Chicago", region: "IL", country: "US", postal_code: "60657", primary: true } ], id_numbers: [ { value: "1234", type: "us_ssn_last_4" } ] } }; try { const response = await client.userCreate(request); } catch (error) { } ``` ```python request = UserCreateRequest( client_user_id="c0e2c4ee-b763-4af5-cfe9-46a46bce883d", identity=ClientUserIdentity( name=ClientUserIdentityName( given_name="Carmen", family_name="Berzatto" ), date_of_birth=date(1987, 1, 31), emails=[ ClientUserIdentityEmail(data="carmy@example.com", primary=True), ClientUserIdentityEmail(data="bear@example.com", primary=False) ], phone_numbers=[ ClientUserIdentityPhoneNumber(data="+13125551212", primary=True) ], addresses=[ ClientUserIdentityAddress( street_1="3200 W Armitage Ave", street_2=None, city="Chicago", region="IL", country="US", postal_code="60657", primary=True ) ], id_numbers=[ UserIDNumber( value="1234", type="us_ssn_last_4" ) ] ) ) response = client.user_create(request) ``` ```ruby request = Plaid::UserCreateRequest.new( client_user_id: "c0e2c4ee-b763-4af5-cfe9-46a46bce883d", identity: { name: { given_name: "Carmen", family_name: "Berzatto" }, date_of_birth: "1987-01-31", emails: [ { data: "carmy@example.com", primary: true }, { data: "bear@example.com", primary: false } ], phone_numbers: [ { data: "+13125551212", primary: true } ], addresses: [ { street_1: "3200 W Armitage Ave", street_2: nil, city: "Chicago", region: "IL", country: "US", postal_code: "60657", primary: true } ], id_numbers: [ { value: "1234", type: "us_ssn_last_4" } ] } ) response = client.user_create(request) ``` ```java ClientUserIdentityAddress addressData = new ClientUserIdentityAddress() .street1("3200 W Armitage Ave") .street2(null) .city("Chicago") .region("IL") .country("US") .postalCode("60657") .primary(true); ClientUserIdentityName name = new ClientUserIdentityName() .givenName("Carmen") .familyName("Berzatto"); ClientUserIdentityEmail email1 = new ClientUserIdentityEmail() .data("carmy@example.com") .primary(true); ClientUserIdentityEmail email2 = new ClientUserIdentityEmail() .data("bear@example.com") .primary(false); ClientUserIdentityPhoneNumber phone1 = new ClientUserIdentityPhoneNumber() .data("+13125551212") .primary(true); UserIDNumber idNumber = new UserIDNumber() .value("1234") .type(IDNumberType.US_SSN_LAST_4); ClientUserIdentity clientUserIdentity = new ClientUserIdentity() .name(name) .dateOfBirth(LocalDate.parse("1987-01-31")) .emails(Arrays.asList(email1, email2)) .phoneNumbers(Arrays.asList(phone1)) .addresses(Arrays.asList(addressData)) .idNumbers(Arrays.asList(idNumber)); UserCreateRequest request = new UserCreateRequest() .clientUserId("c0e2c4ee-b763-4af5-cfe9-46a46bce883d") .identity(clientUserIdentity); Response response = client .userCreate(request) .execute(); ``` ```go city := "Chicago" region := "IL" street := "3200 W Armitage Ave" postalCode := "60657" country := "US" DateOfBirth := "1980-07-31" emails := []string{"carmy@example.com", "bear@example.com"} phoneNumbers := []string{"+13125551212"} firstName := "Carmen" lastName := "Berzatto" ssnLast4 := "1234" addressData := plaid.ClientUserIdentityAddress{ Street1: &street, Street2: nil, City: &city, Region: ®ion, Country: country, PostalCode: &postalCode, Primary: true, } name := plaid.ClientUserIdentityName{ GivenName: firstName, FamilyName: lastName, } clientUserEmails := []plaid.ClientUserIdentityEmail{} for i, e := range emails { clientUserEmails = append(clientUserEmails, plaid.ClientUserIdentityEmail{ Data: e, Primary: i == 0, }) } clientUserPhones := []plaid.ClientUserIdentityPhoneNumber{} for i, p := range phoneNumbers { clientUserPhones = append(clientUserPhones, plaid.ClientUserIdentityPhoneNumber{ Data: p, Primary: i == 0, }) } idNumber := plaid.UserIDNumber{ Value: ssnLast4, Type: "us_ssn_last_4", } clientUserIdentity := plaid.ClientUserIdentity{ Name: &name, DateOfBirth: plaid.NewNullableString(&DateOfBirth), Emails: clientUserEmails, PhoneNumbers: clientUserPhones, Addresses: []plaid.ClientUserIdentityAddress{addressData}, IdNumbers: []plaid.UserIDNumber{idNumber}, } request := plaid.NewUserCreateRequest( "c0e2c4ee-b763-4af5-cfe9-46a46bce883d", ) request.SetIdentity(clientUserIdentity) response, _, err := client.PlaidApi.UserCreate(ctx).UserCreateRequest(*request).Execute() ``` #### Response fields  string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "user_id": "usr_9nSp2KuZ2x4JDw", "request_id": "Aim3b" } ``` \=\*=\*=\*= #### /user/get  #### Retrieve user identity and information  Get user details using a `user_id`. This endpoint only supports users that were created on the new user API flow, without a `user_token`. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/user/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw" }' ``` ```node const request = { user_id: "usr_9nSp2KuZ2x4JDw" }; try { const response = await client.userGet(request); } catch (error) { } ``` ```python request = UserGetRequest( user_id="usr_9nSp2KuZ2x4JDw", ) response = client.user_get(request) ``` ```ruby request = Plaid::UserGetRequest.new( { user_id: "usr_9nSp2KuZ2x4JDw", } ) response = client.user_get(request) ``` ```java UserGetRequest request = new UserGetRequest() .userId("usr_9nSp2KuZ2x4JDw"); Response response = client .userGet(request) .execute(); ``` ```go request := plaid.UserGetRequest{ UserId: plaid.PtrString("usr_9nSp2KuZ2x4JDw"), } response, _, err := client.PlaidApi.UserGet(ctx).UserGetRequest(request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . nullable, string Client provided user ID. string Timestamp of user creation. Format: `date-time` string Timestamp of last user update. Format: `date-time` nullable, object The identity fields associated with a user. For a user to be eligible for a Plaid Check Consumer Report, all fields are required except `id_number`. Providing a partial SSN is strongly recommended, and improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. If creating a report that will be shared with GSEs such as Fannie or Freddie, a full Social Security Number must be provided via the `id_number` field. nullable, object User name information. string User's given name. string User's family name. nullable, string The user's date of birth, to be provided in the format "yyyy-mm-dd". Format: `date` \[object\] The user's emails. string User's email. boolean Indicates whether this is the primary email for the User. \[object\] The user's phone numbers, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. string User's phone number. boolean Indicates whether this is the primary phone number for the User. \[object\] The user's addresses. nullable, string First line of street address. nullable, string Second line of street address. nullable, string City name. nullable, string State, province or region. string Country code. nullable, string Postal or ZIP code. boolean Indicates whether this is the primary address for the User. \[object\] The user's ID numbers. string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` Response Object ```json { "user_id": "usr_8c6ZbDAYjacUXF", "client_user_id": "uid_12345", "created_at": "2019-02-15T15:51:39Z", "updated_at": "2019-02-15T15:52:39Z", "request_id": "m8MDnv9okwxFNBV", "identity": { "name": { "given_name": "Alice", "family_name": "Johnson" }, "date_of_birth": "1988-07-22", "emails": [ { "data": "alice.johnson@example.com", "primary": true }, { "data": "alice.j@workmail.com", "primary": false } ], "phone_numbers": [ { "data": "+15551234567", "primary": true }, { "data": "+15559876543", "primary": false } ], "addresses": [ { "street_1": "123 Main St", "street_2": "Apt 4B", "city": "Anytown", "region": "CA", "country": "US", "postal_code": "90210", "primary": true } ], "id_numbers": [ { "value": "1234", "type": "us_ssn_last_4" } ] } } ``` \=\*=\*=\*= #### /user/update  #### Update user information  This endpoint updates user information for an existing `user_id` or `user_token`. If an existing `user_id` or `user_token` is missing fields required for a given use case (e.g. creating a Consumer Report) use [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) to add values for those fields. Identity updates use merge semantics: provided fields overwrite existing ones; omitted fields remain unchanged. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . object The identity fields associated with a user. For a user to be eligible for a Plaid Check Consumer Report, all fields are required except `id_number`. Providing a partial SSN is strongly recommended, and improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. If creating a report that will be shared with GSEs such as Fannie or Freddie, a full Social Security Number must be provided via the `id_number` field. object User name information. required, string User's given name. required, string User's family name. string The user's date of birth, to be provided in the format "yyyy-mm-dd". Format: `date` \[object\] The user's emails. required, string User's email. required, boolean Indicates whether this is the primary email for the User. \[object\] The user's phone numbers, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. required, string User's phone number. required, boolean Indicates whether this is the primary phone number for the User. \[object\] The user's addresses. string First line of street address. string Second line of street address. string City name. string State, province or region. required, string Country code. string Postal or ZIP code. required, boolean Indicates whether this is the primary address for the User. \[object\] The user's ID numbers. required, string Value of identity document value typed in by user. Alpha-numeric, with all formatting characters stripped. For specific format requirements by ID type, see [Input Validation Rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md#id-numbers) . required, string A globally unique and human readable ID type, specific to the country and document category. For more context on this field, see [Input Validation Rules](https://cognitohq.com/docs/flow/flow-hybrid-input-validation#id-numbers) . Possible values: `ar_dni`, `au_drivers_license`, `au_passport`, `br_cpf`, `ca_sin`, `cl_run`, `cn_resident_card`, `co_nit`, `dk_cpr`, `eg_national_id`, `es_dni`, `es_nie`, `hk_hkid`, `in_pan`, `it_cf`, `jo_civil_id`, `jp_my_number`, `ke_huduma_namba`, `kw_civil_id`, `mx_curp`, `mx_rfc`, `my_nric`, `ng_nin`, `nz_drivers_license`, `om_civil_id`, `ph_psn`, `pl_pesel`, `ro_cnp`, `sa_national_id`, `se_pin`, `sg_nric`, `tr_tc_kimlik`, `us_ssn`, `us_ssn_last_4`, `za_smart_id` string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . object This field is only used by integrations created before December 10, 2025. All other integrations must use the `identity` object instead. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . To create a Plaid Check Consumer Report for a user when using a `user_token`, this field must be present. If this field is not provided during user token creation, you can add it to the user later by calling `/user/update`. Once the field has been added to the user, you will be able to call `/link/token/create` with a non-empty `consumer_report_permissible_purpose` (which will automatically create a Plaid Check Consumer Report), or call `/cra/check_report/create` for that user. required, string The user's first name required, string The user's last name required, \[string\] The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14157452130". Phone numbers provided in other formats will be parsed on a best-effort basis. Phone number input is validated against valid number ranges; number strings that do not match a real-world phone numbering scheme may cause the request to fail, even in the Sandbox test environment. required, \[string\] The user's emails string The user's full social security number. This field should only be provided by lenders intending to share the resulting consumer report with a Government-Sponsored Enterprise (GSE), such as Fannie Mae or Freddie Mac. Format: "ddd-dd-dddd" string The last 4 digits of the user's social security number. Max length: `4` Min length: `4` required, string To be provided in the format "yyyy-mm-dd". This field is required for all Plaid Check customers. Format: `date` required, object Data about the components comprising an address. required, string The full city name required, string The region or state. In API versions 2018-05-22 and earlier, this field is called `state`. Example: `"NC"` required, string The full street address Example: `"564 Main Street, APT 15"` required, string The postal code. In API versions 2018-05-22 and earlier, this field is called `zip`. required, string The ISO 3166-1 alpha-2 country code ```bash curl -X POST https://sandbox.plaid.com/user/update \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw", "identity": { "name": { "given_name": "Carmen", "family_name": "Berzatto" }, "date_of_birth": "1987-01-31", "emails": [ { "data": "carmen@example.com", "primary": true } ], "phone_numbers": [ { "data": "+13125551212", "primary": true }, { "data": "+12125551212", "primary": false } ], "addresses": [ { "street_1": "3200 W Armitage Ave", "street_2": null, "city": "Chicago", "region": "IL", "country": "US", "postal_code": "60657", "primary": true } ], "id_numbers": [ { "value": "1234", "type": "us_ssn_last_4" } ] } }' ``` ```node const request = { user_id: 'usr_9nSp2KuZ2x4JDw', identity: { name: { given_name: "Carmen", family_name: "Berzatto" }, date_of_birth: "1987-01-31", emails: [ { data: "carmy@example.com", primary: true }, { data: "bear@example.com", primary: false } ], phone_numbers: [ { data: "+13125551212", primary: true } ], addresses: [ { street_1: "3200 W Armitage Ave", street_2: null, city: "Chicago", region: "IL", country: "US", postal_code: "60657", primary: true } ], id_numbers: [ { value: "1234", type: "us_ssn_last_4" } ] } }; try { const response = await client.userUpdate(request); } catch (error) { // handle error } ``` ```python request = UserUpdateRequest( user_id='usr_9nSp2KuZ2x4JDw', identity=ClientUserIdentity( name=ClientUserIdentityName( given_name='Carmen', family_name='Berzatto' ), date_of_birth='1987-01-31', emails=[ ClientUserIdentityEmail(data='carmy@example.com', primary=True), ClientUserIdentityEmail(data='bear@example.com', primary=False), ], phone_numbers=[ ClientUserIdentityPhoneNumber(data='+13125551212', primary=True), ], addresses=[ ClientUserIdentityAddress( street_1='3200 W Armitage Ave', street_2=None, city='Chicago', region='IL', country='US', postal_code='60657', primary=True, ) ], id_numbers=[ UserIDNumber( value='1234', type='us_ssn_last_4', ) ] ) ) response = client.user_update(request) ``` ```ruby request = Plaid::UserUpdateRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw', identity: { name: { given_name: "Carmen", family_name: "Berzatto" }, date_of_birth: "1987-01-31", emails: [ { data: "carmy@example.com", primary: true }, { data: "bear@example.com", primary: false } ], phone_numbers: [ { data: "+13125551212", primary: true } ], addresses: [ { street_1: "3200 W Armitage Ave", street_2: nil, city: "Chicago", region: "IL", country: "US", postal_code: "60657", primary: true } ], id_numbers: [ { value: "1234", type: "us_ssn_last_4" } ] } } ) response = client.user_update(request) ``` ```java ClientUserIdentityAddress addressData = new ClientUserIdentityAddress(). street1("3200 W Armitage Ave"). street2(null). city("Chicago"). region("IL"). country("US"). postalCode("60657"). primary(true); ClientUserIdentityName name = new ClientUserIdentityName(). givenName("Carmen"). familyName("Berzatto"); ClientUserIdentityEmail email1 = new ClientUserIdentityEmail(). data("carmy@emample.com"). primary(true); ClientUserIdentityEmail email2 = new ClientUserIdentityEmail(). data("bear@example.com"). primary(false); ClientUserIdentityPhoneNumber phone1 = new ClientUserIdentityPhoneNumber(). data("+13125551212"). primary(true); UserIDNumber idNumber = new UserIDNumber(). value("1234"). type(IDNumberType.US_SSN_LAST_4); ClientUserIdentity clientUserIdentity = new ClientUserIdentity(). name(name). dateOfBirth("1987-01-31"). emails(Arrays.asList(email1, email2)). phoneNumbers(Arrays.asList(phone1)). addresses(Arrays.asList(addressData)). idNumbers(Arrays.asList(idNumber)); UserUpdateRequest request = new UserUpdateRequest() .userId("usr_9nSp2KuZ2x4JDw") .identity(clientUserIdentity); Response response = client .userUpdate(request) .execute(); ``` ```go city := "Chicago" region := "IL" street := "3200 W Armitage Ave" postalCode := "60657" country := "US" emails := []string{"carmy@emample.com", "bear@example.com"} phoneNumbers := []string{"+13125551212"} addressData := plaid.ClientUserIdentityAddress{ Street1: &street, Street2: nil, City: &city, Region: ®ion, Country: country, PostalCode: &postalCode, Primary: true, } name := plaid.ClientUserIdentityName{ GivenName: "Carmen", FamilyName: "Berzatto", } clientUserEmails := []plaid.ClientUserIdentityEmail{} for i, e := range emails { clientUserEmails = append(clientUserEmails, plaid.ClientUserIdentityEmail{ Data: e, Primary: i == 0, }) } clientUserPhones := []plaid.ClientUserIdentityPhoneNumber{} for i, p := range phoneNumbers { clientUserPhones = append(clientUserPhones, plaid.ClientUserIdentityPhoneNumber{ Data: p, Primary: i == 0, }) } idNumber := plaid.UserIDNumber{ Value: "1234", Type: "us_ssn_last_4", } clientUserIdentity := plaid.ClientUserIdentity{ Name: &name, DateOfBirth: plaid.NewNullableString(plaid.PtrString("1987-01-31")), Emails: clientUserEmails, PhoneNumbers: clientUserPhones, Addresses: []plaid.ClientUserIdentityAddress{addressData}, IdNumbers: []plaid.UserIDNumber{idNumber}, } request := plaid.NewUserUpdateRequest() request.SetUserId("usr_9nSp2KuZ2x4JDw") request.SetIdentity(clientUserIdentity) response, _, err := client.PlaidApi.UserUpdate(ctx).UserUpdateRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "Aim3b" } ``` \=\*=\*=\*= #### /user/remove  #### Remove user  [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) deletes a `user_id` or `user_token` and and associated information, including any Items associated with the user. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/user/remove \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw" }' ``` ```node const request = { user_id: 'usr_9nSp2KuZ2x4JDw' }; try { const response = await client.userRemove(request); } catch (error) { // handle error } ``` ```python request = UserRemoveRequest( user_id='usr_9nSp2KuZ2x4JDw', ) response = client.user_remove(request) ``` ```ruby request = Plaid::UserRemoveRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw', } ) response = client.user_remove(request) ``` ```java UserRemoveRequest request = new UserRemoveRequest() .userId("usr_9nSp2KuZ2x4JDw"); Response response = client .userRemove(request) .execute(); ``` ```go request := plaid.UserRemoveRequest{ UserId: plaid.PtrString("usr_9nSp2KuZ2x4JDw"), } response, _, err := client.PlaidApi.UserRemove(ctx).UserRemoveRequest(request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "Aim3b" } ``` \=\*=\*=\*= #### /user/items/get  #### Get Items associated with a User  Returns Items associated with a `user_id`, along with their corresponding statuses. Plaid associates an Item with a User when it has been successfully connected within a Link session initialized with that `user_id`. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/user/items/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw" }' ``` ```node const request = { user_id: 'usr_9nSp2KuZ2x4JDw' }; try { const response = await client.userItemsGet(request); } catch (error) { // handle error } ``` ```python request = UserItemsGetRequest( user_id='usr_9nSp2KuZ2x4JDw', ) response = client.user_items_get(request) ``` ```ruby request = Plaid::UserItemsGetRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw', } ) response = client.user_items_get(request) ``` ```java UserItemsGetRequest request = new UserItemsGetRequest() .userId("usr_9nSp2KuZ2x4JDw"); Response response = client .userItemsGet(request) .execute(); ``` ```go request := plaid.NewUserItemsGetRequest() request.SetUserId("usr_9nSp2KuZ2x4JDw") response, _, err := client.PlaidApi.UserItemsGet(ctx).UserItemsGetRequest(*request).Execute() ``` #### Response fields  \[object\] string The Plaid Item ID. The `item_id` is always unique; linking the same account at the same institution twice will result in two Items with different `item_id` values. Like all Plaid identifiers, the `item_id` is case-sensitive. nullable, string The Plaid Institution ID associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The name of the institution associated with the Item. Field is `null` for Items created without an institution connection, such as Items created via Same Day Micro-deposits. nullable, string The URL registered to receive webhooks for the Item. nullable, string The method used to populate Auth data for the Item. This field is only populated for Items that have had Auth numbers data set on at least one of its accounts, and will be `null` otherwise. For info about the various flows, see our [Auth coverage documentation](https://plaid.com/docs/auth/coverage/index.html.md) . `INSTANT_AUTH`: The Item's Auth data was provided directly by the user's institution connection. `INSTANT_MATCH`: The Item's Auth data was provided via the Instant Match fallback flow. `AUTOMATED_MICRODEPOSITS`: The Item's Auth data was provided via the Automated Micro-deposits flow. `SAME_DAY_MICRODEPOSITS`: The Item's Auth data was provided via the Same Day Micro-deposits flow. `INSTANT_MICRODEPOSITS`: The Item's Auth data was provided via the Instant Micro-deposits flow. `DATABASE_MATCH`: The Item's Auth data was provided via the Database Match flow. `DATABASE_INSIGHTS`: The Item's Auth data was provided via the Database Insights flow. `TRANSFER_MIGRATED`: The Item's Auth data was provided via [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#migrate-account-into-transfers) . `INVESTMENTS_FALLBACK`: The Item's Auth data for Investments Move was provided via a [fallback flow](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . Possible values: `INSTANT_AUTH`, `INSTANT_MATCH`, `AUTOMATED_MICRODEPOSITS`, `SAME_DAY_MICRODEPOSITS`, `INSTANT_MICRODEPOSITS`, `DATABASE_MATCH`, `DATABASE_INSIGHTS`, `TRANSFER_MIGRATED`, `INVESTMENTS_FALLBACK`, `null` nullable, object Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. nullable, string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. nullable, string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. nullable, integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error nullable, string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of products available for the Item that have not yet been accessed. The contents of this array will be mutually exclusive with `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that have been billed for the Item. The contents of this array will be mutually exclusive with `available_products`. Note - `billed_products` is populated in all environments but only requests in Production are billed. Also note that products that are billed on a pay-per-call basis rather than a pay-per-Item basis, such as `balance`, will not appear here. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products added to the Item. In almost all cases, this will be the same as the `billed_products` field. For some products, it is possible for the product to be added to an Item but not yet billed (e.g. Assets, before `/asset_report/create` has been called, or Auth or Identity when added as Optional Products but before their endpoints have been called), in which case the product may appear in `products` but not in `billed_products`. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `payment_initiation`, `identity_verification`, `transactions`, `credit_details`, `income`, `income_verification`, `standing_orders`, `transfer`, `employment`, `recurring_transactions`, `transactions_refresh`, `signal`, `statements`, `processor_payments`, `processor_identity`, `profile`, `cra_base_report`, `cra_income_insights`, `cra_partner_insights`, `cra_network_insights`, `cra_cashflow_insights`, `cra_monitoring`, `cra_lend_score`, `cra_plaid_credit_score`, `layer`, `pay_by_bank`, `protect_linked_bank`, `protect_transactions` \[string\] A list of products that the user has consented to for the Item via [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . This will consist of all products where both of the following are true: the user has consented to the required data scopes for that product and you have Production access for that product. Possible values: `assets`, `auth`, `balance`, `balance_plus`, `beacon`, `identity`, `identity_match`, `investments`, `investments_auth`, `liabilities`, `transactions`, `income`, `income_verification`, `transfer`, `employment`, `recurring_transactions`, `signal`, `statements`, `processor_payments`, `processor_identity`, `cra_base_report`, `cra_income_insights`, `cra_lend_score`, `cra_partner_insights`, `cra_cashflow_insights`, `cra_monitoring`, `layer` nullable, string The date and time at which the Item's access consent will expire, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format. If the Item does not have consent expiration scheduled, this field will be `null`. Currently, only institutions in Europe and a small number of institutions in the US have expiring consent. For a list of US institutions that currently expire consent, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#refreshing-item-consent) . Format: `date-time` string Indicates whether an Item requires user interaction to be updated, which can be the case for Items with some forms of two-factor authentication. `background` - Item can be updated in the background `user_present_required` - Item requires user interaction to be updated Possible values: `background`, `user_present_required` string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "items": [ { "available_products": [ "balance", "auth" ], "billed_products": [ "identity", "transactions" ], "error": null, "institution_id": "ins_109508", "institution_name": "First Platypus Bank", "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr", "update_type": "background", "webhook": "https://plaid.com/example/hook", "consent_expiration_time": null }, { "available_products": [ "balance", "identity", "payment_initiation", "transactions" ], "billed_products": [ "assets", "auth" ], "error": null, "institution_id": "ins_109508", "institution_name": "First Platypus Bank", "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6", "update_type": "background", "webhook": "https://plaid.com/example/hook", "consent_expiration_time": null } ], "request_id": "m8MDnv9okwxFNBV" } ``` \=\*=\*=\*= #### /user/items/remove  This endpoint is currently in early availability. To request access, contact your account manager or [submit a product access support ticket](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . #### Remove Items from a User  Removes specific Items associated with a user. It is equivalent to calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) on each Item individually, but supports use cases (such as Plaid Check) where access tokens are not available. All specified Items must belong to the user or the entire operation fails. Similar to [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) , this deletes Item product data, terminates billing on the Item's products, and fires webhooks to the financial institution. Once removed, Items cannot be reconnected without going through Link again. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. string The user token associated with the User data is being requested for. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . string A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [new user APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . required, \[string\] An array of `item_id`s to be deleted. All Items for removal must be currently associated with the provided `user_id` or `user_token`. Otherwise, the entire operation will error and no Items will be deleted. ```bash curl -X POST https://sandbox.plaid.com/user/items/remove \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "usr_9nSp2KuZ2x4JDw", "item_ids": ["eVBnVMp7zdTJLkRNr33Rs6zr27KeyPMNPqfX1"] }' ``` ```node const request = { user_id: 'usr_9nSp2KuZ2x4JDw', item_ids: ['eVBnVMp7zdTJLkRNr33Rs6zr27KeyPMNPqfX1'], }; try { const response = await client.userItemsRemove(request); } catch (error) { } ``` ```python request = UserItemsRemoveRequest( user_id='usr_9nSp2KuZ2x4JDw', item_ids=['eVBnVMp7zdTJLkRNr33Rs6zr27KeyPMNPqfX1'], ) response = client.user_items_remove(request) ``` ```ruby request = Plaid::UserItemsRemoveRequest.new( { user_id: 'usr_9nSp2KuZ2x4JDw', item_ids: ['eVBnVMp7zdTJLkRNr33Rs6zr27KeyPMNPqfX1'], } ) response = client.user_items_remove(request) ``` ```java UserItemsRemoveRequest request = new UserItemsRemoveRequest() .userId("usr_9nSp2KuZ2x4JDw") .itemIds(Arrays.asList("eVBnVMp7zdTJLkRNr33Rs6zr27KeyPMNPqfX1")); Response response = client .userItemsRemove(request) .execute(); ``` ```go request := plaid.NewUserItemsRemoveRequest( []string{"eVBnVMp7zdTJLkRNr33Rs6zr27KeyPMNPqfX1"}, ) request.SetUserId("usr_9nSp2KuZ2x4JDw") response, _, err := client.PlaidApi.UserItemsRemove(ctx).UserItemsRemoveRequest(*request).Execute() ``` #### Response fields  string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "request_id": "m8MDnv9okwxFNBV" } ``` --- # API - New User API migration guide | Plaid Docs Migrate to new User APIs  ========================= #### Migration guide for existing Consumer Report integrations on legacy User APIs  This guide is for customers who integrated with Consumer Report by Plaid Check (CRA) prior to December 2025. It explains how to migrate your integration from the legacy User APIs and CRA API endpoints (which use `user_token` as the primary identifier) to the new User APIs and updated CRA API endpoints. Migration is optional — your existing integration will continue to work, and there is currently no deadline to migrate. This migration guide applies only to Plaid Check Consumer Report (CRA) customers. If you use the legacy [Plaid Income Verification](https://plaid.com/docs/income/index.html.md) product (non-CRA Bank Income), migration is not yet available. Contact your account manager for timing updates. #### Are you on the legacy API?  All clients who began using [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) on or after December 10, 2025 are on the new User API by default and no migration is needed. If you aren't sure, call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) without `with_upgraded_user: true`. If the response does not include a `user_token`, your client is on the new API by default. If the response includes a `user_token`, then you are eligible to migrate, if you haven't done so already. #### Overview  Plaid's new User APIs introduce a unified user identifier, `user_id`, that is consistent across all Plaid user-based products. For existing CRA customers, the migration has two parts depending on whether a user already exists in your system: **Users you have already created** have a stored `user_token` (format: `user-production-*`). After migration, pass that `user_token` value in the `user_id` field of all CRA API requests and webhook correlation. No changes are needed to the users themselves. **New users created after migration** use the updated [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) schema, which returns a `user_id` (prefixed with `usr_`) instead of a `user_token`. Use that `user_id` in all subsequent API calls. The old [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) response returned both a `user_token` and a legacy `user_id` (an unprefixed string, distinct from the `usr_*`\-prefixed `user_id` used in the new APIs). After migration, set the value of the `user_id` field in API requests to your stored `user_token` — not the legacy `user_id`. #### What's changing  To migrate, you will need to: * **Replace `user_token` with `user_id`** in all CRA API calls, [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , and webhook correlation. For existing users, set the value of the `user_id` field to your stored `user_token` value. * **Update [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate)** to include `with_upgraded_user: true` and replace `consumer_report_user_identity` with the new `identity` schema. [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) is now idempotent: if you call it with a `client_user_id` that already exists, it returns the existing `user_id` rather than an error. * **Update webhook handling** to listen for `USER_CHECK_REPORT_READY` and `USER_CHECK_REPORT_FAILED` instead of `CHECK_REPORT_READY` and `CHECK_REPORT_FAILED`. Cash Flow Updates webhooks are consolidated into a single `CASH_FLOW_INSIGHTS_UPDATED` event. * **Use the new [/user/get](https://plaid.com/docs/api/users/index.html.md#userget) endpoint** to retrieve identity details about any user, including those created via the legacy User API. For full details, see [New User API overview](https://plaid.com/docs/api/users/user-apis/index.html.md) and the migration steps below. #### Migration steps  ##### Update your Plaid client library SDK  Before making any API changes, upgrade your Plaid client library SDK to the minimum version listed below. Older versions do not support the new request schemas and will return errors. Minimum required versions: * Node.js: 41.0.0 * Python: 38.0.0 * Go: 41.0.0 * Java: 39.0.0 * Ruby: 45.0.0 ##### Handle existing users  For users you created via the legacy [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) , you have a stored `user_token` (format: `user-production-*`). When making API calls for them: * Pass your stored `user_token` value in the `user_id` field for all CRA API requests and webhook correlation. * Do not use the legacy `user_id` from the old [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) response — that value is not used for CRA integration after migration. ##### Create new users with the new User API  For new users, call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) with the following changes: * Include `with_upgraded_user: true` in the request body. * Replace `consumer_report_user_identity` with an `identity` object containing `name`, `emails`, `addresses`, `phone_numbers`, `date_of_birth`, and optionally `id_numbers` (last 4 SSN digits). * The response returns a single `user_id` — there is no `user_token`. Store this `user_id` as the identifier for all subsequent API calls and webhooks. /user/create with new User API schema ```bash curl -X POST https://sandbox.plaid.com/user/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_user_id": "c0e2c4ee-b763-4af5-cfe9-46a46bce883d", "with_upgraded_user": true, "identity": { "name": { "given_name": "Carmen", "family_name": "Berzatto" }, "date_of_birth": "1987-01-31", "emails": [ { "data": "carmen@example.com", "primary": true } ], "phone_numbers": [ { "data": "+13125551212", "primary": true } ], "addresses": [ { "street_1": "3200 W Armitage Ave", "city": "Chicago", "region": "IL", "country": "US", "postal_code": "60657", "primary": true } ], "id_numbers": [ { "value": "1234", "type": "us_ssn_last_4" } ] } }' ``` [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) is now idempotent. If you call it with a `client_user_id` that already exists, it returns the existing `user_id` with a `200` status rather than an error. If you include an `identity` object in that call, it will be attached to the existing user. If you don't, a new `user_id` is created and returned with a `201` status. Additionally, in the old flow a `client_user_id` could never be reused to create a new user, even after calling [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) . In the new flow, once [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) has been called on a `user_id`, you can call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) again with the same `client_user_id` to create a new user. When calling the new [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) with a `client_user_id` that was previously created via the legacy API, the response `user_id` may be in `user-production-*` format rather than `usr_*` format. This is expected — [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) returns the existing user with a `200`, and since that user was originally created via the legacy API, its `user_token` has simply become the new `user_id`. For full schema details, see [Updates to user creation and identification](https://plaid.com/docs/api/users/user-apis/index.html.md#updates-to-user-creation-and-identification) and [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . ##### Update Link token creation  In [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , replace the top-level `user_token` field with `user_id`. For existing users, pass your stored `user_token` value in `user_id`. For new users, pass the `user_id` returned by [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . The `user` object is no longer required. Before migration ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user": { "client_user_id": "client-user-id-12345" }, "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", "products": ["cra_base_report", "cra_income_insights", "cra_network_insights"], "webhook": "${WEBHOOK_URL}", "client_name": "Name of App", "consumer_report_permissible_purpose": "ACCOUNT_REVIEW_CREDIT", "country_codes": ["US"], "language": "en", "cra_options": { "days_requested": 365, "base_report": { "client_report_id": "unique_base_report_id" } } }' ``` After migration ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d", # your stored user_token value "products": ["cra_base_report", "cra_income_insights", "cra_network_insights"], "webhook": "${WEBHOOK_URL}", "client_name": "Name of App", "consumer_report_permissible_purpose": "ACCOUNT_REVIEW_CREDIT", "country_codes": ["US"], "language": "en", "cra_options": { "days_requested": 365, "base_report": { "client_report_id": "unique_base_report_id" } } }' ``` ##### Update webhook handling  Update your application to handle the renamed webhook events: | Legacy webhook | New webhook | | --- | --- | | `CHECK_REPORT_READY` | `USER_CHECK_REPORT_READY` | | `CHECK_REPORT_FAILED` | `USER_CHECK_REPORT_FAILED` | | `CASH_FLOW_UPDATES` / `INSIGHTS_UPDATED` / `LARGE_DEPOSIT_DETECTED` / `LOW_BALANCE_DETECTED` / `NEW_LOAN_PAYMENT_DETECTED` / `NSF_OVERDRAFT_DETECTED` | `CASH_FLOW_INSIGHTS_UPDATED` | The `user_id` field in the new webhooks is set to your stored `user_token` value for existing users, and to the `usr_*`\-prefixed `user_id` for users created with the new User API. As of April 1, 2026, existing customers on the legacy APIs automatically began receiving both the new and legacy versions of revised webhooks in parallel. This means you can update your webhook handling at your own pace — your existing integration continues to work throughout. Once you have switched to the new webhook events, you can safely ignore the legacy ones. Recommended approach: * **HTTP layer:** Always return a `2xx` status code for all incoming webhooks. If there is no `200` response or no response within 10 seconds, Plaid retries delivery for up to 24 hours. See [webhook retries](https://plaid.com/docs/api/webhooks/index.html.md#webhook-retries) . * **Application layer:** Route events by `webhook_type` and `webhook_code`. Safely ignore any `webhook_type` values your application does not handle. ##### Retrieve reports for existing users  For existing users, pass your stored `user_token` value in the `user_id` field when calling [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , and other CRA endpoints. The response is identical — only the field name in the request changes. Before migration ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/base_report/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" }' ``` After migration ```bash curl -X POST https://sandbox.plaid.com/cra/check_report/base_report/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user_id": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" # your stored user_token value }' ``` For new users, pass the `user_id` returned by [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) in the `user_id` field. #### Testing the migration  You do not need to create new users to test the migrated API path. Any existing user's `user_token` can be used directly as the `user_id` in the new API fields. 1. Pick any test user already created via the legacy [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint. You'll have a stored `user_token` (format: `user-sandbox-*` in Sandbox, `user-production-*` in Production). 2. Pass that `user_token` value into the `user_id` field in new API calls, for example: * [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) → `user_id` field * [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) → `user_id` field * [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) → `user_id` field 3. Listen for `USER_CHECK_REPORT_READY` and `USER_CHECK_REPORT_FAILED` webhook events and confirm the `user_id` field in the payload matches your stored `user_token`. You can validate the full new flow end-to-end using only existing users in your system, without committing to production migration or creating new users. #### Compatibility: legacy users vs. new users  **Users created via the legacy [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint** (those with a `user-*` format `user_token`) are compatible with both the legacy and new APIs. Their `user_token` value can be passed into the old `user_token` fields or the new `user_id` fields interchangeably during migration. Note that the legacy `user_id` (an unprefixed string also returned by the old [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) ) is not the same as the `user_token` and is not compatible with either the legacy or new API fields — do not use it. **Users created via the new [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate)** (with `with_upgraded_user: true`) receive a `user_id` with a `usr_*` prefix. These users only work with the new APIs — you cannot pass their `user_id` into legacy fields like `user_token` in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) or [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . If you use the new [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) flow in a test environment, make sure your code is already updated to use the new field names. --- # API - New User API overview | Plaid Docs User APIs  ========== #### Information on new user APIs  Plaid is updating our APIs to support the next generation of user-based products - such as Plaid Protect - and to create a more unified and consistent experience across our platform. These updates improve multi-product compatibility, simplify debugging, and ensure user identifiers behave consistently across all Plaid products. If you're beginning a new Plaid Check Consumer Report (CRA) or Multi-Item Link integration in December 2025 or later, you'll use these updated APIs to build your integration. If you are an existing customer using Plaid Check, Plaid Income Verification, or Multi-Item Link as of December 10, 2025, here's what you need to know: * **Your existing integration remains fully supported.** Plaid is not removing support and your integration will continue to function as expected. * **Optional migration is now available for Plaid Check and Multi-Item Link customers.** See the [migration guide](https://plaid.com/docs/api/users/migrate-to-new-user-apis/index.html.md) for step-by-step instructions. #### What's new  ##### Updates to user creation and identification  * When calling [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) , the response includes a single `user_id` instead of a `user_token` and a `user_id`. This `user_id` is used instead of the `user_token` to identify the user throughout the Plaid API, including when calling API endpoints or when receiving webhooks. * A `user_id` created on the new API (prefixed with `usr_`) is not equivalent to a `user_id` (not prefixed with `usr_`) created on the old API. If you have not yet migrated to the updated user APIs, you cannot use a `user_id` in place of a `user_token` for endpoints that accept either identifier. * [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) is now idempotent. In the old flow, when [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) was called on a `client_user_id` more than once, it would return an error; it now returns the same `user_id` as the original call. * The user schema has an `identity` object (instead of the `consumer_report_user_identity` object), which is used in the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) request bodies. This `identity` object has a different schema than the `consumer_report_user_identity` object. ##### Changes to user management  * In the old flow, a `client_user_id` could never be re-used to create a new user, even if the user token was deleted with [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) . In the new flow, once [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) has been called on a `user_id`, a new user can be created for the same `client_user_id` by calling [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . * The endpoint [/user/get](https://plaid.com/docs/api/users/index.html.md#userget) has been added, allowing you to retrieve identity details about a user that you have previously created. ##### Other changes  * The webhooks `CHECK_REPORT_READY` and `CHECK_REPORT_FAILED` have been renamed to `USER_CHECK_REPORT_READY` and `USER_CHECK_REPORT_FAILED`. * For Cash Flow Insights (beta) customers, the different Insights webhooks have been replaced by a single webhook, `CASH_FLOW_INSIGHTS_UPDATED`, with an `insights` payload field listing all of the insights received. Existing customers who are migrating will receive both the new and old sets of webhooks in parallel during migration, allowing you to cut over at your own pace. #### Who gets the new user APIs  As of December 10, 2025, all Plaid customers will experience the new user API behavior by default, with the following exceptions: * Any existing Plaid customers who ever used the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint in either Sandbox or Production as of December 10, 2025, will automatically be kept on the old user API behavior, to avoid breaking changes. This group includes all existing and currently integrating customers of Consumer Report, Multi-Item Link, and/or Income Verification. * New customers of the legacy [Plaid Income Verification](https://plaid.com/docs/income/index.html.md) product should contact sales, Support, or their account manager to request access to the old user APIs. Note that this applies only to the legacy Plaid Income Verification product; it does not apply to the Plaid Check Consumer Report Income modules, such as Base Report and Income Insights. If you aren't sure whether you have the new or old API, call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . * In the new API, the response will not include a `user_token`, and your `user_id` will be formatted with the prefix `usr_`. * In the old API, the response will include a `user_token`, and the `user_id` will not contain a prefix. #### Client library version requirements  To use the new user APIs with a Plaid client library, the minimum client library versions are: * Python: 38.0.0 * Go: 41.0.0 * Java: 39.0.0 * Node: 41.0.0 * Ruby: 45.0.0 #### Summary  **New clients integrating with Plaid Check or Multi-Item Link** beginning December 10, 2025 or later should use the new `user_id` based implementation currently described in the docs. **Existing users of other Plaid products** who are integrating with Plaid Check or Multi-Item Link for the first time beginning December 10, 2025 or later should use the new `user_id` based implementation currently described in the docs. They may also need to [update their client library versions](https://plaid.com/docs/api/users/user-apis/index.html.md#client-library-version-requirements) . **New clients using Plaid's legacy (non-CRA) Bank Income product** for the first time beginning December 10, 2025 or later should contact their account manager or file a support ticket via the Dashboard to request access to the `user_token` field. **Existing clients already using Plaid Check or Multi-Item Link products** can now optionally migrate to the new user APIs. Migration is recommended but not required — your existing integration will continue to function. See the [migration guide](https://plaid.com/docs/api/users/migrate-to-new-user-apis/index.html.md) for step-by-step instructions. During migration, you will receive both the legacy and new webhook events in parallel until you complete the cutover. If you have questions about migration readiness or how the new user APIs might benefit your integration, contact your Plaid account manager. --- # API - API versioning | Plaid Docs API versioning and changelog  ============================= #### Keep track of changes and updates to the Plaid API  #### API versioning  This page covers backwards-incompatible, versioned API changes. For a list of all API updates, including non-versioned ones, see the [changelog](https://plaid.com/docs/changelog/index.html.md) . Whenever we make a backwards-incompatible change to a general availability, non-beta product, we release a new API version to avoid causing breakages for existing developers. You can then continue to use the old API version, or update your application to upgrade to the new Plaid API version. APIs for beta products are subject to breaking changes without versioning, with 30 days notice. We consider the following changes to be backwards compatible (non-breaking): * Adding new API endpoints * Adding new optional parameters to existing endpoints * Adding new data elements to existing response schemas or webhooks * Adding new enum values, including `error_types` and `error_codes` * Subdividing existing `error_codes` into more precise errors, and changing the http response code as necessary, as long as the error cannot be resolved via in-app logic (such as launching update mode or waiting for a few seconds and retrying) during runtime. For example, changing `PRODUCT_NOT_READY` errors to a different `error_code` would be a breaking change, since that error can be resolved by retrying a few seconds later, but converting an existing `INTERNAL_SERVER_ERROR` to a more specific error would not be. * Changing the behavior for use cases or platforms that are explicitly not supported. * Adding new `webhook_types` and `webhook_codes` * Changing the length or content of any API identifier ##### How to set your API version  The default version of the API used in any requests you make can be configured in the [Dashboard](https://dashboard.plaid.com/developers/api) and will be used when version information is not otherwise specified. You can also manually set the `Plaid-Version` header to use a specific version for a given API request. If you're using one of the Plaid client libraries, they should all be pinned to the latest version of the API at the time when they were released. This means that you can change the API version you're using by updating to a newer version of the client library. ```node const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments[process.env.PLAID_ENV], baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, 'Plaid-Version': '2020-09-14', }, }, }); const client = new PlaidApi(configuration); ``` ```ruby require 'plaid' configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] =ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] configuration.api_key['Plaid-Version'] = '2020-09-14' api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) ``` ```java import com.plaid.client.ApiClient; import com.plaid.client.request.PlaidApi; // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); ``` ```python from plaid.api import plaid_api configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, 'plaidVersion': '2020-09-14' } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) ``` ```go import ( "github.com/plaid/plaid-go/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", {VALUE}) configuration.AddDefaultHeader("PLAID-SECRET", {VALUE}) configuration.AddDefaultHeader("Plaid-Version", "2020-09-14") configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) ``` ```bash curl -X POST https://sandbox.plaid.com/auth/get \ -H 'Content-Type: application/json' \ -H 'Plaid-Version: 2020-09-14' ``` #### Version 2020-09-14  This version includes several changes to improve authentication, streamline and simplify the API, and improve international support. * To improve authentication, the `public_key` has been fully removed from the API. Endpoints that previously accepted a `public_key` for authentication, namely [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) and [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) , now require a `client_id` and `secret` for authentication instead. * [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) no longer returns a `removed` boolean. This field created developer confusion, because it was never possible for it to return `false`. A failed [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) call will result in an [error](https://plaid.com/docs/errors/index.html.md) being returned instead. * Several undocumented and unused fields have been removed from the `institution` object returned by the institutions endpoints [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) , [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) , and [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) . The removed fields are: `input_spec`, `credentials`, `include_display_data`, `has_mfa`, `mfa`, and `mfa_code_type`. * The institutions endpoints [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) , [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) , and [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) now require the use of a `country_codes` parameter and no longer use `US` as a default value if `country_codes` is not specified, as this behavior caused confusion and unexpected behavior for non-US developers. As part of this change, the `country_codes` parameter has been moved out of the `options` object and is now a top-level parameter. * To support international payments, the response schema for the partner-only [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) endpoint has changed. The 2018-05-22 and 2019-05-29 API releases previously extended the response schema for [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) in order to support international accounts, but these changes were never extended to the [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) endpoint. This release brings the response for [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) in line with the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) response, allowing Plaid partners to extend support for using non-ACH payment methods, such as EFT payments (Canada) or SEPA credit and direct debit (Europe). Accommodating this change does not require any code changes from Plaid developers who use partnership integrations, only from the Plaid partners themselves. Previous /processor/auth/get response ```json "numbers": [{ "account": "9900009606", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "routing": "011401533", "wire_routing": "021000021" }] ``` 2020-09-14 API version /processor/auth/get response ```json "numbers": { "ach": [{ "account": "9900009606", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "routing": "011401533", "wire_routing": "021000021" }], "eft":[{ "account": "111122223333", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "institution": "021", "branch": "01140" }], "international":[{ "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "bic": "NWBKGB21", "iban": "GB29NWBK60161331926819" }], "bacs":[{ "account": "31926819", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "sort_code": "601613" }] } ``` #### Version 2019-05-29  * The Auth `numbers` schema has been extended to support BACS (UK) and other international (IBAN and BIC) account numbers used across the EU. * Renamed the `zip` field to `postal_code` and the `state` field to `region` in all [Identity](https://plaid.com/docs/api/products/identity/index.html.md) and [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md) responses to be more international friendly. * [Identity](https://plaid.com/docs/api/products/identity/index.html.md) objects in [Identity responses](https://plaid.com/docs/api/products/identity/index.html.md) are now embedded on the `owners` field of the corresponding account. * Address data fields for [Identity](https://plaid.com/docs/api/products/identity/index.html.md) responses are now nullable and are returned with a null value when they aren't available rather than an empty string. * Added a ISO-3166-1 alpha-2 `country` field to all [Identity](https://plaid.com/docs/api/products/identity/index.html.md) and [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md) responses. * The account type `brokerage` has been renamed to `investment`. These changes are meant to enable access to International institutions for Plaid's launch in Europe and add support for investment accounts. Test in the [Sandbox](https://plaid.com/docs/sandbox/index.html.md) with the new API version to see the new Schema and enable support for International institutions from the [Dashboard](https://dashboard.plaid.com/developers/api) in order to create Items for these institutions. ##### Auth  Before, `numbers` only had fields for `ach` (US accounts) and `eft` (Canadian accounts) accounts numbers: Previous Auth response (2018-05-22 version) ```json "numbers": { "ach": [{ "account": "9900009606", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "routing": "011401533", "wire_routing": "021000021" }], "eft":[{ "account": "111122223333", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "institution": "021", "branch": "01140" }] } ``` Now, the structure of `numbers` hasn't changed, but it can have `ach`, `eft`, `bacs` (UK accounts), or `international` (currently EU accounts) numbers. Note that the schema for each of these numbers are different from one another. It is possible for multiple networks to be present in the response. New Auth response (2019-05-29 version) ```json "numbers": { "ach": [{ "account": "9900009606", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "routing": "011401533", "wire_routing": "021000021" }], "eft":[{ "account": "111122223333", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "institution": "021", "branch": "01140" }], "international":[{ "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "bic": "NWBKGB21", "iban": "GB29NWBK60161331926819" }], "bacs":[{ "account": "31926819", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "sort_code": "601613" }] } ``` ##### Identity  The previous version of [Identity](https://plaid.com/docs/api/products/identity/index.html.md) had US specific field names and did not include a country as part of the location. Furthermore, the identity data was not scoped to a specific account. Previous Identity response (2018-05-22 version) ```json "identity": { "addresses": [{ "accounts": [ "Plaid Checking 0000", "Plaid Saving 1111", "Plaid CD 2222" ], "data": { "city": "Malakoff", "state": "NY", "street": "2992 Cameron Road", "zip": "14236" }, "primary": true }], ... } ``` Now, `identity` has international friendly field names of `region` and `postal_code` instead of `zip` and `state` as well as a ISO-3166-1 alpha-2 `country` field. Address data fields (`city`, `region`, `street`, `postal_code`, and `country`) are now nullable and are returned with a `null` value when they aren't available rather than as an empty string. The identity object is now available on the "owners" key of the account, which represents ownership of specific accounts. New Identity response (2019-05-29 version) ```json "accounts": [{ ... "owners": [{ "addresses": [{ "data": { "city": "Malakoff", "region": "NY", "street": "2992 Cameron Road", "postal_code": "14236", "country": "US" }, "primary": true }] }], ... }] ``` ##### Transactions  When no transactions are returned from a request, the `transactions` object will now be `null` rather than an empty array. In addition, the same changes to [Identity](https://plaid.com/docs/api/products/identity/index.html.md) were also made to [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md) . Previous Transactions response (2018-05-22 version) ```json "transactions": [{ ... "location": { "address": "300 Post St", "city": "San Francisco", "state": "CA", "zip": "94108", "lat": null, "lon": null }, ... ]} ``` New Transactions response (2019-05-29 version) ```json "transactions": [{ ... "location": { "address": "300 Post St", "city": "San Francisco", "region": "CA", "postal_code": "94108", "country": "US", "lat": null, "lon": null }, ... ]} ``` ##### Institutions  Changes to the institutions schema effects responses from all of the institutions API endpoints: * POST [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) * POST [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) * POST [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) The previous version of the Institution schema did not include the country of the institution as part of the response. Previous Institution response (2018-05-22 version) ```json "institution": { "credentials": [{ "label": "User ID", "name": "username", "type": "text" }, { "label": "Password", "name": "password", "type": "password" }], "has_mfa": true, "institution_id": "ins_109512", "mfa": [ "code", "list", "questions", "selections" ], "name": "Houndstooth Bank", "products": [ "auth", "balance", "identity", "transactions" ], // included when options.include_status is true "status": {object} } ``` New Institution response (2019-05-29 version) ```json "institution": { "country_codes": ["US"], "credentials": [{ "label": "User ID", "name": "username", "type": "text" }, { "label": "Password", "name": "password", "type": "password" }], "has_mfa": true, "institution_id": "ins_109512", "mfa": [ "code", "list", "questions", "selections" ], "name": "Houndstooth Bank", "products": [ "auth", "balance", "identity", "transactions" ], // included when options.include_status is true "status": {object} } ``` #### Version 2018-05-22  * The Auth `numbers` schema has changed to support ACH (US-based) and EFT (Canadian-based) account numbers * Added the `iso_currency_code` and `unofficial_currency_code` fields to all [Accounts](https://plaid.com/docs/api/accounts/index.html.md#accounts-get-response-accounts) and [Transactions](https://plaid.com/docs/api/products/transactions/index.html.md) responses Enable support for Canadian institutions from the [Dashboard](https://dashboard.plaid.com/developers/api) and then test in the [Sandbox](https://plaid.com/docs/sandbox/index.html.md) using the test Canadian institution, Tartan-Dominion Bank of Canada (institution ID `ins_43`). Before, `numbers` was a list of objects, each one representing the account and routing number for an ACH-eligible US checking or savings account: Previous Auth response (2017-03-08 version) ```json "numbers": [{ "account": "9900009606", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "routing": "011401533", "wire_routing": "021000021" }] ``` **New Auth response (2018-05-22 version)** Now, `numbers` can have either `ach` (US accounts) or `eft` (Canadian accounts) numbers. Note that the schema for `ach` numbers and `eft` numbers are different from one another. New Auth response (2018-05-22 version) for ACH numbers ```json "numbers": { "ach": [{ "account": "9900009606", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "routing": "011401533", "wire_routing": "021000021" }], "eft": [] } ``` New Auth response (2018-05-22 version) for EFT numbers ```json "numbers": { "ach":[], "eft":[{ "account": "111122223333", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "institution": "021", "branch": "01140" }] } ``` #### Version 2017-03-08  The `2017-03-08` version was the first versioned release of the API. --- # API - Webhooks | Plaid Docs Webhooks  ========= #### API reference for webhooks  Prefer to learn by watching? Our [video tutorial](https://www.youtube.com/watch?v=0E0KEAVeDyc) walks you through the basics of incorporating Plaid webhooks into your application. Looking for webhook schemas? The reference documentation for specific webhooks ([Transactions](https://plaid.com/docs/api/products/transactions/index.html.md#webhooks) , [Auth](https://plaid.com/docs/api/products/auth/index.html.md#webhooks) , [Assets](https://plaid.com/docs/api/products/assets/index.html.md#webhooks) , [Identity](https://plaid.com/docs/api/products/identity/index.html.md#webhooks-beta) , [Identity Verification](https://plaid.com/docs/api/products/identity-verification/index.html.md#webhooks) , [Monitor](https://plaid.com/docs/api/products/monitor/index.html.md) , [Investments](https://plaid.com/docs/api/products/investments/index.html.md#webhooks) , [Liabilities](https://plaid.com/docs/api/products/liabilities/index.html.md#webhooks) , [Payment Initiation](https://plaid.com/docs/api/products/payment-initiation/index.html.md#webhooks) , [Income](https://plaid.com/docs/api/products/income/index.html.md#webhooks) , [Virtual Accounts](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#webhooks) , [Items](https://plaid.com/docs/api/items/index.html.md#webhooks) , and [Transfer](https://plaid.com/docs/api/products/transfer/index.html.md) ) has moved to its respective API reference pages. #### Introduction to webhooks  A webhook is an HTTP request used to provide push notifications. Plaid sends webhooks to programmatically inform you about changes to Plaid Items or the status of asynchronous processes. For example, Plaid will send a webhook when an Item is in an error state or has additional data available, or when a non-blocking process (like gathering transaction data or verifying a bank account via micro-deposits) is complete. To receive Plaid webhooks, set up a dedicated endpoint on your server as a webhook listener that can receive POST requests, then provide this endpoint URL to Plaid as described in the next section. You can also test webhooks without setting up your own endpoint following the instructions in [Testing webhooks in Sandbox](https://plaid.com/docs/api/webhooks/index.html.md#testing-webhooks-in-sandbox) . #### Configuring webhooks  Webhooks are typically configured via the `webhook` parameter of [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , although some webhooks (especially those used in contexts where Link tokens are not always required), such as Identity Verification webhooks, are configured via the [Plaid Dashboard](https://dashboard.plaid.com/developers/webhooks) instead. When specifying a webhook, the URL must be in the standard format of `http(s)://(www.)domain.com/` and, if https, must have a valid SSL certificate. To view response codes and debug any issues with webhook setup, see the [Logs section in the Dashboard](https://dashboard.plaid.com/activity/logs) . Plaid sends POST payloads with raw JSON to your webhook URL from one of the following IP addresses: * 52.21.26.131 * 52.21.47.157 * 52.41.247.19 * 52.88.82.239 Note that these IP addresses are subject to change. You can optionally verify webhooks to ensure they are from Plaid. For more information, see [webhook verification](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md) . #### Webhook retries  If there is a non-200 response or no response within 10 seconds from the webhook endpoint, Plaid will keep attempting to send the webhook for up to 24 hours. Each attempt will be tried after a delay that is 4 times longer than the previous delay, starting with 30 seconds. To avoid unnecessary retries, Plaid won't retry webhooks if we detect that the webhook receiver endpoint has rejected more than 90% of webhooks sent by Plaid over the last 24 hours. If your endpoint returns a `429 Too Many Requests` response, Plaid will honor the `Retry-After` header if present, waiting the specified duration for up a maximum of 4 hours later before the next attempt instead of applying the standard exponential backoff. The `Retry-After` value may be an integer number of seconds (e.g. `120`), an HTTP date (e.g. `Wed, 21 Oct 2026 07:28:00 GMT`), or an ISO 8601 timestamp (e.g. `2026-10-21T07:28:00Z`). #### Best practices for applications using webhooks  You should design your application to handle duplicate and out-of-order webhooks. Ensure [idempotency](https://martinfowler.com/articles/patterns-of-distributed-systems/idempotent-receiver.html) on actions you take when receiving a webhook. If you drive application state with webhooks, ensure your code doesn't rely on a specific order of webhook receipt. If you (or Plaid) experience downtime for longer than Plaid's [retry period](https://plaid.com/docs/api/webhooks/index.html.md#webhook-retries) , you will lose webhooks. Ensure your application can recover by implementing endpoint polling or other appropriate logic if a webhook is not received within an expected window. All data present in webhooks is also present in our other APIs. It's best to keep your receiver as simple as possible, such as a receiver whose only job is to write the webhook into a queue or reliable storage. This is important for two reasons. First, if the receiver does not respond within 10 seconds, the delivery is considered failed. Second, because webhooks can arrive at unpredictable rates. Therefore if you do a lot of work in your receiver - e.g. generating and sending an email - spikes are likely to overwhelm your downstream services, or cause you to be rate-limited if the downstream is a third-party. #### Testing webhooks in Sandbox  Webhooks will fire as normal in the Sandbox environment, with the exception of Transfer webhooks. For testing purposes, you can also use [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) , [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) , or [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) to fire a webhook on demand. If you don't have a webhook endpoint configured yet, you can also use a tool such as [Webhook.site](https://webhook.site) or [Request Bin](https://requestbin.com/) to quickly and easily set up a webhook listener endpoint. When directing webhook traffic to third-party tools, make sure you are using Plaid's Sandbox environment and not sending out live data. #### Example in Plaid Pattern  For real-life examples of handling webhooks that illustrate how to handle sample transactions and Item webhooks, see [handleTransactionsWebhook.js](https://github.com/plaid/pattern/blob/master/server/webhookHandlers/handleTransactionsWebhook.js) and [handleItemWebhook.js](https://github.com/plaid/pattern/blob/master/server/webhookHandlers/handleItemWebhook.js) These files contain webhook handling code for the Node-based [Plaid Pattern](https://github.com/plaid/pattern) sample app. --- # API - Webhook verification | Plaid Docs Verify webhooks  ================ #### API reference for verifying webhooks  Plaid signs all outgoing webhooks so that you can verify the authenticity of any incoming webhooks to your application. A message signature is included in the `Plaid-Verification` header (Note: this is the canonical representation of the header field, but HTTP 1.x headers should be handled as [case-insensitive](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) , HTTP 2 headers are always lowercase). The verification process is optional and is not required for your application to handle Plaid webhooks. The verification process requires understanding JSON Web Tokens (JWTs) and JSON Web Keys (JWKs). More information about these specifications can be found at [jwt.io](http://www.jwt.io) . Libraries for interpreting and verifying JWKs and JWTs most likely exist in your preferred language. It is highly recommended that you utilize well-tested libraries rather than trying to implement these specifications from scratch. #### Steps to verify webhooks  ##### Extract the JWT header  Extract the Plaid-Verification HTTP header from any Plaid webhook (to get a webhook, see [firing webhooks in Sandbox](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) ). The value of the Plaid-Verification header is a JWT, and will be referred to as "the JWT" in following steps. Using your preferred JWT library, decode the JWT and extract the header without validating the signature. This functionality most likely exists in your preferred JWT library. An example JWT header is shown below. JWT header ```json { "alg": "ES256", "kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c", "typ": "JWT" } ``` Ensure that the value of the `alg` (algorithm) field in the header is `"ES256"`. Reject the webhook if this is not the case. Extract the value corresponding to the `kid` (key ID) field. This will be used to retrieve the JWK public key corresponding to the private key that was used to sign this request. ##### Get the verification key  Use the [/webhook\_verification\_key/get](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md#get-webhook-verification-key) endpoint to get the webhook verification key. \=\*=\*=\*= #### /webhook\_verification\_key/get  #### Get webhook verification key  Plaid signs all outgoing webhooks and provides JSON Web Tokens (JWTs) so that you can verify the authenticity of any incoming webhooks to your application. A message signature is included in the `Plaid-Verification` header. The [/webhook\_verification\_key/get](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md#get-webhook-verification-key) endpoint provides a JSON Web Key (JWK) that can be used to verify a JWT. #### Request fields  string Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. string Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. required, string The key ID ( `kid` ) from the JWT header. ```bash curl -X POST https://production.plaid.com/webhook_verification_key/get \ -H 'content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "key_id": String }' ``` ```node const request: WebhookVerificationKeyGetRequest = { key_id: keyID, }; try { const response = await plaidClient.webhookVerificationKeyGet(request); const key = response.data.key; } catch (error) { // handle error } ``` ```ruby request = Plaid::WebhookVerificationKeyGetRequest.new({ key_id: key_id }) response = client.webhook_verification_key_get(request) key = response[:key] ``` ```go webhookReq := plaid.NewWebhookVerificationKeyGetRequest("KEY_ID") webhookResp, _, err := client.PlaidApi.WebhookVerificationKeyGet(ctx).WebhookVerificationKeyGetRequest(*webhookReq).Execute() if err != nil { // handle error } key := webhookResp.GetKey() ``` ```python request = WebhookVerificationKeyGetRequest(key_id=key_id) response = client.webhook_verification_key_get(request) key = response['key'] ``` ```java WebhookVerificationKeyGetRequest request = new WebhookVerificationKeyGetRequest() .keyId(keyId); Response response = client() .webhookVerificationKeyGet(request) .execute(); WebhookVerificationKey key = response.body().getKey(); ``` #### Response fields  object A JSON Web Key (JWK) that can be used in conjunction with [JWT libraries](https://jwt.io/#libraries-io) to verify Plaid webhooks string The alg member identifies the cryptographic algorithm family used with the key. string The crv member identifies the cryptographic curve used with the key. string The kid (Key ID) member can be used to match a specific key. This can be used, for instance, to choose among a set of keys within the JWK during key rollover. string The kty (key type) parameter identifies the cryptographic algorithm family used with the key, such as RSA or EC. string The use (public key use) parameter identifies the intended use of the public key. string The x member contains the x coordinate for the elliptic curve point, provided as a base64url-encoded string of the coordinate's big endian representation. string The y member contains the y coordinate for the elliptic curve point, provided as a base64url-encoded string of the coordinate's big endian representation. integer The timestamp when the key was created, in Unix time. nullable, integer The timestamp when the key expired, in Unix time. string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. Response Object ```json { "key": { "alg": "ES256", "created_at": 1560466150, "crv": "P-256", "expired_at": null, "kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c", "kty": "EC", "use": "sig", "x": "hKXLGIjWvCBv-cP5euCTxl8g9GLG9zHo_3pO5NN1DwQ", "y": "shhexqPB7YffGn6fR6h2UhTSuCtPmfzQJ6ENVIoO4Ys" }, "request_id": "RZ6Omi1bzzwDaLo" } ``` ##### Validate the webhook  Interpret the returned `key` as a JWK public key. Using your preferred JWT library, verify the JWT using the JWK. If the signature is not valid, reject the webhook. Otherwise, extract the payload of the JWT. It will look something like the JSON below. JWT Payload ```json { "iat": 1560211755, "request_body_sha256": "bbe8e9..." } ``` Use the issued at time denoted by the `iat` field to verify that the webhook is not more than 5 minutes old. Rejecting outdated webhooks can help prevent replay attacks. Extract the value of the `request_body_sha256` field. This will be used to check the integrity and authenticity of the webhook body. Compute the SHA-256 of the webhook body and ensure that it matches what is specified in the `request_body_sha256` field of the validated JWT. If not, reject the webhook. It is best practice to use a constant time string/hash comparison method in your preferred language to prevent timing attacks. Note that the `request_body_sha256` sent in the JWT payload is sensitive to the whitespace in the webhook body and uses a tab-spacing of 2. If the webhook body is stored with a tab-spacing of 4, the hash will not match. #### Example implementation  The following code shows one example method that can be used to verify webhooks sent by Plaid and cache public keys. ```python import hashlib import hmac import time import requests from jose import jwt # Plaid client credentials. Fetch these from your secrets manager or similar storage. CLIENT_ID = 'PLAID_CLIENT_ID' SECRET = 'PLAID_SECRET' # Endpoint for getting public verification keys. ENDPOINT = 'https://production.plaid.com/webhook_verification_key/get' # Single cached key instead of a dictionary CACHED_KEY = None def verify(body, headers): global CACHED_KEY signed_jwt = headers.get('plaid-verification') current_key_id = jwt.get_unverified_header(signed_jwt)['kid'] # Fetch key if not already cached if CACHED_KEY is None: response = requests.post(ENDPOINT, json={ 'client_id': CLIENT_ID, 'secret': SECRET, 'key_id': current_key_id }) if response.status_code != 200: return False CACHED_KEY = response.json()['key'] # If key is still not set, verification fails if CACHED_KEY is None: return False # Validate the signature and extract the claims. try: claims = jwt.decode(signed_jwt, CACHED_KEY, algorithms=['ES256']) except jwt.JWTError: return False # Ensure that the token is not expired. if claims["iat"] < time.time() - 5 * 60: return False # Compute the hash of the body. m = hashlib.sha256() m.update(body.encode()) body_hash = m.hexdigest() # Ensure that the hash of the body matches the claim. return hmac.compare_digest(body_hash, claims['request_body_sha256']) ``` ```ruby require 'digest' require 'jwt' require 'time' require 'base64' require 'openssl' require 'json' require 'jose' require 'active_support/security_utils' require 'plaid' module PlaidWebhookVerifier def self.verify(body, headers) # Cache for webhook validation key. @cached_key ||= nil client = Plaid::ApiClient.new(env: PLAID_ENV, client_id: PLAID_CLIENT_ID, secret: PLAID_SECRET) signed_jwt = headers['plaid-verification'] decoded_token = JWT.decode signed_jwt, nil, false current_key_id = decoded_token[1]['kid'] # Fetch key if not already cached unless @cached_key request = Plaid::WebhookVerificationKeyGetRequest.new({ key_id: current_key_id }) response = client.webhook_verification_key_get(request) @cached_key = response.key end # If key is still not set, verification fails return false unless @cached_key # Validate the signature begin return false unless JOSE::JWT.verify(@cached_key, signed_jwt)[0] rescue return false end # Compare hashes body_hash = Digest::SHA256.hexdigest(body) claimed_body_hash = decoded_token[0]["request_body_sha256"] return false unless ActiveSupport::SecurityUtils.secure_compare(body_hash, claimed_body_hash) # Validate that token is not expired iat = decoded_token[0]["iat"] return false if Time.now.to_i - iat > 60 * 5 true end end ``` ```bash # Not applicable ``` ```java import com.plaid.client.model.WebhookVerificationKeyGetRequest; import com.plaid.client.model.WebhookVerificationKeyGetResponse; import com.plaid.client.request.PlaidApi; import com.plaid.client.ApiClient; import com.auth0.jwt.JWT; import com.auth0.jwt.interfaces.DecodedJWT; import com.auth0.jwt.interfaces.JWTVerifier; import com.auth0.jwt.algorithms.Algorithm; import com.auth0.jwt.exceptions.JWTVerificationException; import com.nimbusds.jose.jwk.ECKey; import com.google.common.hash.Hashing; import retrofit2.Response; import org.json.JSONObject; import java.util.Base64; import java.nio.charset.StandardCharsets; import java.security.interfaces.ECPublicKey; import java.util.HashMap; import java.util.Map; private static PlaidApi plaidClient; private static JSONObject cachedKey = null; public static boolean verifyWebhook(String body, HashMap headers) { // Instantiate Plaid client (usually you'd do this elsewhere, shown for context) HashMap apiKeys = new HashMap<>(); apiKeys.put("clientId", "YOUR_CLIENT_ID"); apiKeys.put("secret", "YOUR_CLIENT_SECRET"); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Extract the signed JWT from the webhook header String signedToken = headers.get("plaid-verification"); // Decode the signed JWT returned by Plaid DecodedJWT decodedToken = JWT.decode(signedToken); String decodedTokenHeader = decodedToken.getHeader(); // Convert String token header to JSON Object JSONObject decodedTokenHeaderJson = new JSONObject(decodedTokenHeader); // Return false if alg in header is not "ES256" if (!decodedTokenHeaderJson.getString("alg").equals("ES256")) { return false; } // Extract the key id, "kid", from the decoded token header String currentKid = decodedTokenHeaderJson.getString("kid"); // Fetch key if not already cached if (cachedKey == null) { try { WebhookVerificationKeyGetRequest request = new WebhookVerificationKeyGetRequest() .keyId(currentKid); Response response = plaidClient .webhookVerificationKeyGet(request) .execute(); if (response.body() == null) { return false; } // Read verification key as JSON cachedKey = new JSONObject(response.body().getKey().toString()); } catch (Exception e) { return false; } } // If key is still not set, verification fails if (cachedKey == null) { return false; } // Create ECPublicKey from JSON string, needed for Algorithm instance ECPublicKey ecpkVerificationKey; try { ecpkVerificationKey = ECKey.parse(cachedKey.toString()).toECPublicKey(); } catch (Exception e) { return false; } try { // Set up the algorithm needed to verify token Algorithm algorithm = Algorithm.ECDSA256(ecpkVerificationKey, null); // Verify the token JWTVerifier verifier = JWT.require(algorithm) .acceptLeeway(300) // 5 minutes .build(); // Reusable verifier instance DecodedJWT verifiedJwt = verifier.verify(signedToken); // Extract payload of verified token String payload = verifiedJwt.getPayload(); // Decode Base64 encoded payload to String String payloadDecoded = new String(Base64.getDecoder().decode(payload), StandardCharsets.UTF_8); // Convert String payload to JSON Object JSONObject payloadJson = new JSONObject(payloadDecoded); // Extract value of 'request_body_sha256' field in payload String sha256InPayload = payloadJson.getString("request_body_sha256"); // Compute sha256 of webhook body using Google's Guava library String sha256OfWebhookBody = Hashing.sha256() .hashString(body, StandardCharsets.UTF_8) // Compute sha256 of body .toString(); return sha256OfWebhookBody.equals(sha256InPayload); } catch (JWTVerificationException exception) { return false; } } ``` ```node const compare = require('secure-compare'); const { jwtDecode } = require('jwt-decode'); // syntax for jwtDecode 4.0 or later const JWT = require('jose'); const sha256 = require('js-sha256'); const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); // Single cached key instead of a Map let cachedKey = null; const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const plaidClient = new PlaidApi(configuration); const verify = async (body, headers) => { const signedJwt = headers['plaid-verification']; const decodedToken = jwtDecode(signedJwt); const decodedTokenHeader = jwtDecode(signedJwt, { header: true }); const currentKeyID = decodedTokenHeader.kid; // Fetch key if not already cached if (!cachedKey) { try { const response = await plaidClient.webhookVerificationKeyGet({ key_id: currentKeyID, }); cachedKey = response.data.key; } catch (error) { return false; } } // If key is still not set, verification fails if (!cachedKey) { return false; } // Validate the signature and iat try { const keyLike = await JWT.importJWK(cachedKey); // This will throw an error if verification fails await JWT.jwtVerify(signedJwt, keyLike, { maxTokenAge: '5 min', }); } catch (error) { return false; } // Compare hashes const bodyHash = sha256(body); const claimedBodyHash = decodedToken.request_body_sha256; return compare(bodyHash, claimedBodyHash); }; ``` ```go package main import ( "context" "crypto/ecdsa" "crypto/elliptic" "crypto/sha256" "crypto/subtle" "encoding/base64" "encoding/hex" "errors" "fmt" "math/big" "strings" "time" "github.com/golang-jwt/jwt/v4" "github.com/plaid/plaid-go/v40/plaid" ) // helper method func jwkToECDSAPublicKey(jwk *plaid.JWKPublicKey) (*ecdsa.PublicKey, error) { if jwk == nil || jwk.X == "" || jwk.Y == "" || jwk.Kty == nil || *jwk.Kty != "EC" || jwk.Crv == nil || *jwk.Crv != "P-256" { return nil, errors.New("invalid/unsupported JWK") } xBytes, err := base64.RawURLEncoding.DecodeString(jwk.X) if err != nil { return nil, fmt.Errorf("decode x: %w", err) } yBytes, err := base64.RawURLEncoding.DecodeString(jwk.Y) if err != nil { return nil, fmt.Errorf("decode y: %w", err) } return &ecdsa.PublicKey{ Curve: elliptic.P256(), X: new(big.Int).SetBytes(xBytes), Y: new(big.Int).SetBytes(yBytes), }, nil } var ( jwkCache = map[string]*plaid.JWKPublicKey{} maxAge = 5 * time.Minute ) func verifyWebhook(ctx context.Context, client *plaid.APIClient, webhookBody []byte, headers map[string]string) (bool, error) { tokenString := getHeaderCI(headers, "Plaid-Verification") if tokenString == "" { return false, errors.New("missing Plaid-Verification header") } // Decode JWT header (unverified) to extract alg and kid parser := jwt.Parser{} unverified, _, err := parser.ParseUnverified(tokenString, jwt.MapClaims{}) if err != nil { return false, fmt.Errorf("parse unverified token: %w", err) } if unverified.Method.Alg() != jwt.SigningMethodES256.Alg() { return false, fmt.Errorf("unexpected alg %q (want ES256)", unverified.Method.Alg()) } kid, _ := unverified.Header["kid"].(string) if kid == "" { return false, errors.New("missing kid in JWT header") } // Get verification key for kid via /webhook_verification_key/get jwk, err := getJWK(ctx, client, kid) if err != nil { return false, fmt.Errorf("get JWK: %w", err) } pubKey, err := jwkToECDSAPublicKey(jwk) if err != nil { return false, fmt.Errorf("jwk->ecdsa: %w", err) } // Verify JWT signature claims := jwt.MapClaims{} token, err := jwt.ParseWithClaims(tokenString, claims, func(t *jwt.Token) (interface{}, error) { if t.Method != jwt.SigningMethodES256 { return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"]) } return pubKey, nil }) if err != nil || !token.Valid { return false, fmt.Errorf("invalid token: %w", err) } // Verify that the webhook is not more than 5 minutes old iatVal, ok := claims["iat"] if !ok { return false, errors.New("missing iat") } var iat time.Time switch v := iatVal.(type) { case float64: iat = time.Unix(int64(v), 0) case int64: iat = time.Unix(v, 0) default: return false, errors.New("invalid iat type") } if time.Since(iat) > maxAge { return false, errors.New("token too old (>5m)") } // Verify body hash integrity wantHash, ok := claims["request_body_sha256"].(string) if !ok || wantHash == "" { return false, errors.New("missing request_body_sha256") } sum := sha256.Sum256(webhookBody) gotHex := strings.ToLower(hex.EncodeToString(sum[:])) if subtle.ConstantTimeCompare([]byte(gotHex), []byte(strings.ToLower(wantHash))) != 1 { return false, errors.New("body hash mismatch") } return true, nil } func getHeaderCI(h map[string]string, name string) string { lname := strings.ToLower(name) for k, v := range h { if strings.ToLower(k) == lname { return v } } return "" } func getJWK(ctx context.Context, client *plaid.APIClient, kid string) (*plaid.JWKPublicKey, error) { if key, ok := jwkCache[kid]; ok && key != nil { return key, nil } req := *plaid.NewWebhookVerificationKeyGetRequest(kid) resp, _, err := client.PlaidApi.WebhookVerificationKeyGet(ctx). WebhookVerificationKeyGetRequest(req). Execute() if err != nil { return nil, err } key := resp.GetKey() if key.Kid != nil && *key.Kid == kid { jwkCache[kid] = &key } return &key, nil } ``` --- # Assets - Create an Asset Report | Plaid Docs Create an Asset Report  ======================= #### Learn how to create Asset Reports with the Assets product  In this guide, we'll start from scratch and walk through how to use [Assets](https://plaid.com/docs/api/products/assets/index.html.md) to generate and retrieve Asset Reports. If a user's Asset Report involves data from multiple financial institutions, the user will need to allow access to each institution, which will in turn enable you to access their data from each institution. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to [Creating Asset Reports](https://plaid.com/docs/assets/add-to-app/index.html.md#creating-asset-reports) . #### Get Plaid API keys and complete application and company profile  If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard. You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard. This will provide basic information about your app to help users manage their connection on the Plaid Portal at [my.plaid.com](https://my.plaid.com) . The application profile and company profile must be completed before connecting to certain institutions in Production. #### Install and initialize Plaid libraries  You can use our official server-side client libraries to connect to the Plaid API from your application: ```node // Install via npm npm install --save plaid ``` ```bash ## Not applicable with curl calls ``` ```ruby # Available as a gem gem install plaid ``` ```java /* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ implementation "com.plaid:plaid-java:{VERSION}" /* For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ com.plaid plaid-java {VERSION} ``` ```python # Install through pip, only supports Python 3 pip install --upgrade plaid-python ``` ```go go get github.com/plaid/plaid-go ``` After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include it in any other calls. ```node // Using Express const express = require('express'); const app = express(); app.use(express.json()); const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const client = new PlaidApi(configuration); ``` ```bash ## Not applicable with curl calls ``` ```ruby require 'sinatra' require 'plaid' set :port, ENV['APP_PORT'] || 8000 configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) ``` ```java import java.net.*; import java.io.*; import retrofit2.Response; import java.util.Arrays; import com.sun.net.httpserver.*; import com.plaid.client.ApiClient; import com.plaid.client.request.PlaidApi; public class PlaidExample { private static final String CLIENT_ID = System.getenv("PLAID_CLIENT_ID"); private static final String SECRET = System.getenv("PLAID_SECRET"); public static void main(String[] args) { HttpServer server = HttpServer.create( new InetSocketAddress("localhost", 8000), 0); server.createContext("/create_link_token", new GetLinkToken()); server.setExecutor(null); server.start(); } // Additional server code goes here } ``` ```python import plaid from plaid.api import plaid_api from flask import Flask from flask import render_template from flask import request from flask import jsonify app = Flask(name) configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Additional server code goes here if __name__ == "__main__": app.run(port=8000) ``` ```go import ( "context" "net/http" "os" "github.com/gin-gonic/gin" "github.com/plaid/plaid-go/v3/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) func main() { r := gin.Default() // Server endpoints would be declared here // e.g. r.POST("/create_link_token", createLinkToken) r.POST("/create_link_token", createLinkToken) err := r.Run(":8000") if err != nil { panic("unable to start server") } } ``` #### Create an Item in Link  Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. Asset Reports can consist of user data from multiple financial institutions; users will need to use Link to provide access to each financial institution, providing you with multiple Items. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) . Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created. Since, for Assets, users may need to grant access to more than one financial institution via Link, you may need to initialize Link more than once. In the code samples below, you will need to replace `PLAID_CLIENT_ID` and `PLAID_SECRET` with your own keys, which you can obtain from the [Dashboard](https://dashboard.plaid.com/developers/keys) . ##### Create a link\_token  ```node app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['assets'], language: 'en', webhook: 'https://webhook.example.com', redirect_uri: 'https://domainname.com/oauth-page.html', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "products": ["assets"], "country_codes": ["US"], "language": "en", "webhook": "https://webhook.example.com", "redirect_uri": "https://domainname.com/oauth-page.html" }' ``` ```ruby post '/api/create_link_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: client_user_id }, client_name: 'Plaid Test App', products: ['assets'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.example.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.Products; import com.plaid.client.model.CountryCode; import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; public class PlaidExample { ... static class GetLinkToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.fromValue("assets"))) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .redirectUri("https://domainname.com/oauth-page.html") .webhook("https://webhook.example.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.link_token_create_request import LinkTokenCreateRequest from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser from plaid.model.products import Products from plaid.model.country_code import CountryCode @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( products=[Products("assets")], client_name="Plaid Test App", country_codes=[CountryCode('US')], redirect_uri='https://domainname.com/oauth-page.html', language='en', webhook='https://webhook.example.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetRedirectUri("https://domainname.com/oauth-page.html") request.SetProducts([]plaid.Products{plaid.PRODUCTS_ASSETS}) resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` ##### Install Link dependency  index.html ```html Connect a bank ``` ##### Configure the client-side Link handler  app.js ```javascript const linkHandler = Plaid.create({ token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token to your app server. $.post('/exchange_public_token', { public_token: public_token, }); }, onExit: (err, metadata) => { // Optionally capture when your user exited the Link flow. // Storing this information can be helpful for support. }, onEvent: (eventName, metadata) => { // Optionally capture Link flow events, streamed through // this callback as your users connect an Item to Plaid. }, }); linkHandler.open(); ``` #### Get a persistent access\_token  Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id` for each Item the user provided you with via Link. The `access_token` will allow us to make authenticated calls to the Plaid API for its corresponding financial institution. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call. Save the `access_token`s and `item_id`s in a secure datastore, as they're used to access `Item` data and identify `webhooks`, respectively. An `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . An `access_token` should be stored securely and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it. ```node app.post('/api/exchange_public_token', async function ( request, response, next, ) { const publicToken = request.body.public_token; try { const tokenResponse = await client.itemPublicTokenExchange({ public_token: publicToken, }); // These values should be saved to a persistent database and // associated with the currently signed-in user const accessToken = tokenResponse.data.access_token; const itemID = tokenResponse.data.item_id; response.json({ public_token_exchange: 'complete' }); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-12345678-abcd-1234-abcd-1234567890ab" }' ``` ```ruby access_token = nil post '/api/exchange_public_token' do request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: params["public_token"] } ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response.access_token item_id = response.item_id content_type :json {public_token_exchange: "complete"}.to_json end ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; public class PlaidExample { ... static class GetAccessToken implements HttpHandler { private static PlaidClient plaidClient; private String publicToken; private String accessToken; private String itemId; public void handle(HttpExchange t) throws IOException { // Simplified pseudo-code for obtaining public_token InputStream is = t.getRequestBody(); publicToken = is.publicToken(); // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange public_token for an access_token ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response response = plaidClient .itemPublicTokenExchange(request) .execute(); // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken = response.body().getAccessToken(); itemId = response.body().getItemId(); String message = "{\"public_token_exchange\": \"complete\"}"; return Response .status(Response.Status.OK) .entity(message) .type(MediaType.APPLICATION_JSON) } } } ``` ```python access_token = None item_id = None @app.route('/exchange_public_token', methods=['POST']) def exchange_public_token(): global access_token public_token = request.form['public_token'] request = ItemPublicTokenExchangeRequest( public_token=public_token ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response['access_token'] item_id = response['item_id'] return jsonify({'public_token_exchange': 'complete'}) ``` ```go func getAccessToken(c *gin.Context) { ctx := context.Background() publicToken := c.PostForm("public_token") // exchange the public_token for an access_token exchangePublicTokenReq := plaid.NewItemPublicTokenExchangeRequest(publicToken) exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *exchangePublicTokenReq, ).Execute() // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken := exchangePublicTokenResp.GetAccessToken() itemID := exchangePublicTokenResp.GetItemId() c.JSON(http.StatusOK, gin.H{"public_token_exchange": "complete"}) } ``` #### Creating Asset Reports  Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API and create an Asset Report using the [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) endpoint. ##### Assets sample request: create  ```python import plaid from plaid.model.asset_report_create_request import AssetReportCreateRequest from plaid.model.asset_report_create_request_options import AssetReportCreateRequestOptions from plaid.model.asset_report_user import AssetReportUser # access_tokens is a list of Item access tokens. # Note that the assets product must be enabled for all Items. # All fields on the options object are optional. request = AssetReportCreateRequest( access_tokens=[access_token], days_requested=90, options=AssetReportCreateRequestOptions( webhook='https://www.example.com', client_report_id='123', user=AssetReportUser( client_user_id='789', first_name='Jane', middle_name='Leah', last_name='Doe', ssn='123-45-6789', phone_number='(555) 123-4567', email='jane.doe@example.com', ) ) ) response = client.asset_report_create(request) asset_report_id = response['asset_report_id'] asset_report_token = response['asset_report_token'] ``` ```ruby require 'plaid' # access_tokens is a list of Item access tokens. # Note that the assets product must be enabled for all Items. # All fields on the options Hash are optional. options = { client_report_id: '123', webhook: 'https://www.example.com', user: { client_user_id: '789', first_name: 'Jane', middle_name: 'Leah', last_name: 'Doe', ssn: '123-45-6789', phone_number: '(555) 123-4567', email: 'jane.doe@example.com', }, } request = Plaid::AssetReportCreateRequest.new( { access_tokens: [access_token], days_requested: 90, options: options } ) response = client.asset_report_create(request) asset_report_id = response.asset_report_id asset_report_token = response.asset_report_token ``` ```go import ( "context" "github.com/plaid/plaid-go/v40/plaid" ) request := plaid.NewAssetReportCreateRequest(2) request.SetAccessTokens([]string{accessToken}) response, _, err := client.PlaidApi.AssetReportCreate(ctx).AssetReportCreateRequest( *request, ).Execute() ``` ```bash curl -X POST https://sandbox.plaid.com/asset_report/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_tokens": [String], "days_requested": Integer, "options": { // all optional "client_report_id": String, "webhook": String, "user": { // all optional "client_user_id": String, "first_name": String, "middle_name": String, "last_name": String, "ssn": String, "phone_number": String, "email": String } } }' ``` ```java import com.plaid.client.model.AssetReportCreateRequest; import com.plaid.client.model.AssetReportCreateRequestOptions; import com.plaid.client.model.AssetReportUser; import com.plaid.client.model.AssetReportCreateResponse; // access_tokens is an array of Item access tokens. // Note that the assets product must be enabled for all Items. // All fields on the options object are optional. AssetReportCreateRequest assetReportCreateRequest = new AssetReportCreateRequest() .accessTokens(access_tokens) .daysRequested(90); AssetReportUser assetReportUser = new AssetReportUser() .firstName("Alberta") .middleName("Bobbeth") .lastName("Charleson"); AssetReportCreateRequestOptions assetReportCreateOptions = new AssetReportCreateRequestOptions() .user(assetReportUser) .webhook(webhookUrl); assetReportCreateRequest.options(assetReportCreateOptions); Response response = client .assetReportCreate(assetReportCreateRequest) .execute(); String assetReportId = response.body().getAssetReportId(); String assetReportToken = response.body().getAssetReportToken(); ``` ```node const { AssetReportCreateRequest } = require('plaid'); const daysRequested = 90; const options = { client_report_id: '123', webhook: 'https://www.example.com', user: { client_user_id: '789', first_name: 'Jane', middle_name: 'Leah', last_name: 'Doe', ssn: '123-45-6789', phone_number: '(555) 123-4567', email: 'jane.doe@example.com', }, }; const request: AssetReportCreateRequest = { access_tokens: [accessToken], days_requested, options, }; // accessTokens is an array of Item access tokens. // Note that the assets product must be enabled for all Items. // All fields on the options object are optional. try { const response = await plaidClient.assetReportCreate(request); const assetReportId = response.data.asset_report_id; const assetReportToken = response.data.asset_report_token; } catch (error) { // handle error } ``` Sample response data is below. Assets response: create ```json { "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a", "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb", "request_id": "Iam3b" } ``` #### Fetching asset data  Once an Asset Report has been created, it can be retrieved to analyze the user's loan eligibility. For more detailed information on the schema for Asset Reports, see [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) . Asset Reports are not generated instantly. If you receive a `PRODUCT_NOT_READY` error when calling [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) , the requested Asset Report has not yet been generated. To be alerted when the requested Asset Report has been generated, listen to [Assets webhooks](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) . ##### Assets sample request: get  ```go import ( "context" "github.com/plaid/plaid-go/v40/plaid" ) request := plaid.NewAssetReportGetRequest() request.SetAssetReportToken(assetReportToken) response, _, err := client.PlaidApi.AssetReportGet(ctx).AssetReportGetRequest(*request).Execute() ``` ```bash curl -X POST https://sandbox.plaid.com/asset_report/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "asset_report_token": String, "include_insights": Boolean }' ``` ```python import plaid from plaid.model.asset_report_get_request import AssetReportGetRequest # asset_report_token is the token from the AssetReport.create response. try: request = AssetReportGetRequest(asset_report_token=asset_report_token) response = client.asset_report_get(request) report = response['report'] except plaid.ApiException as e: if e.code == 'PRODUCT_NOT_READY': # Asset report is not ready yet. Try again later. else: # Handle error. ``` ```java import com.plaid.client.model.AssetReportGetRequest; import com.plaid.client.model.AssetReportGetResponse; // assetReportToken is the token from the AssetReportCreateRequest response. AssetReportGetRequest request = new AssetReportGetRequest() .includeInsights(true) .assetReportToken(assetReportToken); Response response = client().assetReportGet(request).execute(); AssetReport report = response.body().getReport(); ``` ```ruby require 'plaid' # asset_report_token is the token from the AssetReport.create response. request = Plaid::AssetReportGetRequest.new({ asset_report_token: asset_report_token }) response = client.asset_report_get(request) report = response.report ``` ```node const { AssetReportGetRequest } = require('plaid'); const request: AssetReportGetRequest = { asset_report_token: assetReportToken, include_insights: true, }; try { const response = await plaidClient.assetReportGet(request); const assetReportId = response.data.asset_report_id; } catch (error) { // handle error } ``` Sample response data is below. Assets response: get ```json { "report": { "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d", "client_report_id": "123abc", "date_generated": "2020-06-05T22:47:53Z", "days_requested": 2, "items": [ { "accounts": [ { "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "balances": { "available": 200, "current": 210, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "days_available": 2, "historical_balances": [ { "current": 210, "date": "2020-06-04", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 210, "date": "2020-06-03", "iso_currency_code": "USD", "unofficial_currency_code": null } ], "mask": "1111", "name": "Plaid Saving", "official_name": "Plaid Silver Standard 0.1% Interest Saving", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "postal_code": "93405-2255", "region": "CA", "street": "2493 Leisure Lane" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": ["Alberta Bobbeth Charleson"], "phone_numbers": [ { "data": "1112223333", "primary": false, "type": "home" }, { "data": "1112225555", "primary": false, "type": "mobile1" } ] } ], "ownership_type": null, "subtype": "savings", "transactions": [], "type": "depository" }, { "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J", "balances": { "available": null, "current": 56302.06, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "days_available": 2, "historical_balances": [], "mask": "8888", "name": "Plaid Mortgage", "official_name": null, "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "postal_code": "93405-2255", "region": "CA", "street": "2493 Leisure Lane" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": ["Alberta Bobbeth Charleson"], "phone_numbers": [ { "data": "1112223333", "primary": false, "type": "home" }, { "data": "1112225555", "primary": false, "type": "mobile1" } ] } ], "ownership_type": null, "subtype": "mortgage", "transactions": [], "type": "loan" }, { "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "balances": { "available": null, "current": 410, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "days_available": 2, "historical_balances": [ { "current": 410, "date": "2020-06-04", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 410, "date": "2020-06-03", "iso_currency_code": "USD", "unofficial_currency_code": null } ], "mask": "3333", "name": "Plaid Credit Card", "official_name": "Plaid Diamond 12.5% APR Interest Credit Card", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "postal_code": "93405-2255", "region": "CA", "street": "2493 Leisure Lane" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "extraordinarily.long.email.username.123456@reallylonghostname.com", "primary": false, "type": "other" } ], "names": ["Alberta Bobbeth Charleson"], "phone_numbers": [ { "data": "1112223333", "primary": false, "type": "home" }, { "data": "1112225555", "primary": false, "type": "mobile1" } ] } ], "ownership_type": null, "subtype": "credit card", "transactions": [], "type": "credit" } ], "date_last_updated": "2020-06-05T22:47:52Z", "institution_id": "ins_3", "institution_name": "Chase", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6" } ], "user": { "client_user_id": "123456789", "email": "accountholder0@example.com", "first_name": "Alberta", "last_name": "Charleson", "middle_name": "Bobbeth", "phone_number": "111-222-3333", "ssn": "123-45-6789" } }, "request_id": "eYupqX1mZkEuQRx", "warnings": [] } ``` #### Working with Assets data  After your initial [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) and [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) requests, you may want your application to fetch updated Asset Reports, provide Audit Copies of Asset Reports, and more. Consult the [API Reference](https://plaid.com/docs/api/products/assets/index.html.md) to explore these and other options. #### Next steps  If you're ready to launch to Production, see the Launch checklist. #### Launch checklist  Recommended steps to take before launching in Production [Launch](https://plaid.com/docs/launch-checklist/index.html.md) --- # Assets - Introduction to Assets | Plaid Docs Introduction to Assets   ======================== #### Access users' financial information for loan underwriting  Get started with Assets [API Reference](https://plaid.com/docs/api/products/assets/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md) [Demo](https://plaid.coastdemo.com/share/66fb0a180582208ffa82103e?zoom=100) #### Overview  Most new customers should use [Consumer Report by Plaid Check](https://plaid.com/docs/check/index.html.md) instead of Assets. Consumer Report is an FCRA-compliant product providing underwriting scores and insights, as well as Day 1 Certainty compatible Asset Verification reports for mortgage lending. Assets is currently recommended only for use cases not supported by Consumer Report, such as underwriting outside the US. Assets data is used to determine whether a user has enough assets to qualify for a loan. Plaid's Assets product allows you to access a user's Asset Report via the [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) (JSON) and [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) (PDF) endpoints. Asset Reports are created on a per-user basis and include a snapshot of information about a user's identity, transaction history, account balances, and more. [Prefer to learn by watching? Get an overview of how Assets works in just 3 minutes!](https://www.youtube.com/watch?v=98Lq6Fb-bwo) For a fuller view of a borrower's financial situation, Assets can be used with [Bank Income](https://plaid.com/docs/income/index.html.md) , which provides user-permissioned income streams derived from deposit activity. If you need exact copies of a user's statements, see [Statements](https://plaid.com/docs/statements/index.html.md) . #### No-code integration with the Credit Dashboard  The Credit Dashboard is currently in beta. To request access, contact your account manager. To use the Credit Dashboard for Assets, you must not be using any [Plaid Check](https://plaid.com/docs/check/index.html.md) products. Assets data is available via a no-code integration through the [Credit Dashboard](https://dashboard.plaid.com/credit) . You can fill out a form with basic information about your end user, such as their name and email address, and indicate how much history you would like to collect and whether you would like to enable [Bank Income](https://plaid.com/docs/income/bank-income/index.html.md) for the session as well. Plaid will then generate a hyperlink that can be used to launch a Plaid-hosted Link session. Plaid can email the link directly to your user (Production only, not available in Sandbox), or you can send it to them yourself. After the end user successfully completes the Link session, their data will be available in the Dashboard for you to view, archive, or delete. The data shown will be the same data returned by a regular Assets call, in a user-friendly web-based session. (An image of "Plaid Assets Dashboard: Summary tab with Profile, Income, and Accounts info. Shows user's reference ID, income, and bank accounts.") This integration is also compatible with Income, and you can enable Assets and Income in the same session. Once you are enabled for the Credit Dashboard, all new sessions, including ones created via the API, will be displayed in the Dashboard. Data from Link sessions created via the Credit Dashboard cannot be accessed via the Plaid API. If you require programmatic access to data, use the [code-based integration flow](https://plaid.com/docs/assets/index.html.md#integration-overview) instead. #### Integration overview  There are a few steps you will need to take to obtain an Asset Report for a particular user. 1. First, using the Link flow, [create Items](https://plaid.com/docs/api/items/index.html.md#token-exchange-flow) for each of the user's financial institutions; in doing so, you will obtain an `access_token` for each institution. You can use these tokens to obtain an Asset Report as long as the `access_token` was generated with `assets` included in Link's `product` array. With Assets, the user, upon using Link to authenticate with their financial institution, will need to provide consent for Plaid to access account balances, account holder information, and transaction history for that institution. Should the user revoke access via [my.plaid.com](https://my.plaid.com/) , Plaid will notify you via a [webhook](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) . 2. Once you have the required `access_token`s, call the [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) endpoint to create an Asset Report. Note that Asset Reports are not created instantly. When the Asset Report is ready, you will be notified via a [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) webhook. If low latency is important to your use case, you can call [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) with `options.add_ons` set to `["fast_assets"]`. This will cause Plaid to create two versions of the Asset Report: one with only current and available balance and identity information, and then later on the complete Asset Report. You will receive separate webhooks for each version of the Asset Report. 3. After receiving the [PRODUCT\_READY](https://plaid.com/docs/api/products/assets/index.html.md#product_ready) webhook, you can retrieve an Asset Report in JSON format by calling the [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) endpoint. To retrieve an Asset Report in PDF format, call the [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) endpoint. To retrieve an Asset Report with cleaned and categorized transactions as well as additional information about merchants and locations in JSON format, call the [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) endpoint with `include_insights=true`. If you enabled Fast Assets when calling [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) , you can request the Fast version of the Asset Report by calling [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) with `fast_report=true`. 4. Sometimes, third party auditors need to see Asset Reports to audit lenders' decision making processes. To provide an Audit Copy of an Asset Report to a requesting third party, call the [/asset\_report/audit\_copy/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copycreate) endpoint and provide the auditor with an `audit_copy_token`. The auditor needs to be integrated with Plaid in order to view Audit Copies. Currently, Fannie Mae, Freddie Mac, and Ocrolus are the only auditors integrated with Plaid. Sample asset report ```json { "report": { "asset_report_id": "ebb8f490-8f45-4c93-a6c3-5801bf92c3ff", "client_report_id": null, "date_generated": "2023-12-18T07:20:25Z", "days_requested": 2, "items": [ { "accounts": [ { "account_id": "1Gd3X8NmgLFVn47RorabTJ7Bvy8vBqfpaG5Ky", "balances": { "available": null, "current": 320.76, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "days_available": 0, "historical_balances": [], "mask": "5555", "name": "Plaid IRA", "official_name": null, "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "1112225555", "primary": false, "type": "mobile" } ] } ], "ownership_type": null, "subtype": "ira", "transactions": [], "type": "investment" }, { "account_id": "7B73zkZlnLfeWMvkAlxpslbR4PM4RECdaKgll", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "days_available": 2, "historical_balances": [ { "current": 110, "date": "2023-12-17", "iso_currency_code": "USD", "unofficial_currency_code": null }, { "current": 116.33, "date": "2023-12-16", "iso_currency_code": "USD", "unofficial_currency_code": null } ], "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "postal_code": "93405-2255", "region": "CA", "street": "2493 Leisure Lane" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "1112223333", "primary": false, "type": "home" } ] } ], "ownership_type": null, "subtype": "checking", "transactions": [ { "account_id": "7B73zkZlnLfeWMvkAlxpslbR4PM4RECdaKgll", "amount": 6.33, "date": "2023-12-09", "iso_currency_code": "USD", "original_description": "Uber 072515 SF**POOL**", "pending": false, "transaction_id": "mqdZ1xRbjau73pER6NrPSZQXZKQdN8CgLKrXA", "unofficial_currency_code": null } ], "type": "depository" } ], "date_last_updated": "2023-12-18T07:16:21Z", "institution_id": "ins_3", "institution_name": "Chase", "item_id": "KEv98XqZ7yudGRpDqaxJsZ3PKDGzR8CRM13nr" } ], "user": { "client_user_id": null, "email": null, "first_name": null, "last_name": null, "middle_name": null, "phone_number": null, "ssn": null } }, "request_id": "AYRjla7HgW4nKM9", "warnings": [] } ``` The `report` field of the above object contains the body of the Asset Report. This field consists of several subfields that contain information about the date and time the Asset Report was created; data submitted about the user; and information about Items, containing the user's historical balances, identity information, and more for each of the user's financial institutions. For a full explanation of the `report` field and its subfields, consult the [API Reference](https://plaid.com/docs/api/products/assets/index.html.md) . #### Assets webhooks  When you create an Asset Report, Plaid aggregates account balances, account holder identity information, and transaction history for the duration specified. If you attempt to retrieve an Asset Report before the requested data has been collected, you'll receive a response with the HTTP status code 400 and a Plaid error code of `PRODUCT_NOT_READY`. To remove the need for polling, Plaid sends a webhook to the URL you supplied when creating the Asset Report once the Report has been generated. If generation fails, the webhook will indicate why. For examples of webhooks corresponding to successful and unsuccessful Asset Report generation, see the [API Reference for Assets webhooks](https://plaid.com/docs/api/products/assets/index.html.md#webhooks) . #### Refreshing Asset Reports  Asset Reports can either be created or removed; they cannot be updated. To retrieve up-to-date information about users' transactions and balances, call the [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) endpoint. This endpoint, when used, creates a new Asset Report based on the corresponding existing Asset Report. #### Getting an Asset Report for an existing Item  If your user has already connected their account to your application for a different product, you can add Assets to the existing Item via [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . To do so, in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request, populate the `access_token` field with the access token for the Item, and set the `products` array to `["assets"]`. If the user connected their account less than two years ago, they can bypass the Link credentials pane and complete just the Asset Report consent step. Otherwise, they will be prompted to complete the full Link flow. #### Financial Account Matching  If you are already using [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) , you can enhance your verification process by enabling [Financial Account Matching](https://plaid.com/docs/identity-verification/index.html.md#financial-account-matching) in your Identity Verification template. This feature allows you to compare the data collected during KYC with the bank account data collected when creating an Asset Report. To ensure accurate matching, it's important to maintain consistency in the `client_user_id` used for end users across all products. #### Financial Insights Reports (UK only)  In the UK, the Financial Insights Report, including risk and affordability insights, is available as an optional add-on to Assets. Risk insights provides details on instances of potential risks such as loan disbursements, loan payments, gambling, bank penalties, and negative balances. Affordability insights provides insights based on spending / income ratios, considering factors such as essential vs. non-essential spend and other financial commitments. Like Asset Reports, Financial Insights Reports are available in both JSON and PDF format. [View a sample Financial Insights Report (UK only) PDF](https://plaid.com/documents/sample-financial-insights-report.pdf) . To learn more about Financial Insights Reports or to request pricing details, [contact sales](https://plaid.com/contact/) or your Plaid account manager. #### Testing Assets  Assets can be tested in [Sandbox](https://plaid.com/docs/sandbox/index.html.md) without any additional permissions and can be tested with live data using a [Trial plan](https://plaid.com/docs/sandbox/index.html.md#testing-with-live-data-using-a-trial-plan) . Plaid provides a [GitHub repo](https://github.com/plaid/sandbox-custom-users/) with test data for testing Assets in Sandbox, beyond that provided by the default Sandbox user. For more information on configuring custom Sandbox data, see [Configuring the custom user account](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuring-the-custom-user-account) . #### Attributes library  Plaid provides a GitHub [Credit attributes library](https://github.com/plaid/credit-attributes) with Python scripts that can be used to derive various useful information from Asset Reports. #### Assets pricing  Assets is billed on a [flexible fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flexible-fee) ; the cost will depend on the number of Items in the Asset Report (there is an additional cost for Asset Reports with more than 5 Items), as well as whether Additional History (over 61 days of history) has been requested for the report. Audit copies and PDF Asset Reports are billed based on a [per-request model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) . #### Next steps  To learn more about building with Assets, see [Create an Asset Report](https://plaid.com/docs/assets/add-to-app/index.html.md) and the [API Reference](https://plaid.com/docs/api/products/assets/index.html.md) . For a more detailed overview of the steps involved in creating a full implementation of Plaid Assets, see the [Plaid Assets Solution Guide](https://plaid.com/documents/plaid-assets-solution-guide.pdf) . If you're ready to launch to Production, see the Launch checklist. #### Launch Center  See next steps to launch in Production [Launch](https://dashboard.plaid.com/developers/launch-center) --- # Assets - Assets partners | Plaid Docs Assets Partners  ================ #### Find providers who have partnered with Plaid to provide Assets verification  #### Overview  | Partner | Description | | --- | --- | | [Alloy](https://plaid.com/docs/assets/partnerships/alloy/index.html.md) | Offers identity data orchestration and credit decisioning to financial services companies looking to address fraud and uphold compliance (US only) | | [Ocrolus](https://plaid.com/docs/assets/partnerships/ocrolus/index.html.md) | Provides digitized Asset documentation verification (US only) | For more information, see the list of partners in the [Plaid Dashboard](https://dashboard.plaid.com/developers/integrations) . --- # Assets - Ocrolus | Plaid Docs Add Ocrolus to your app  ======================== #### Use Ocrolus with Plaid Assets to digitize data collection  (An image of "Logos of Plaid and Ocrolus side by side.") Plaid and Ocrolus have partnered to offer lenders an easier way to access bank data to make informed loan decisions. Plaid enables businesses to instantly connect a customer's bank account, giving them the ability to authenticate and retrieve account details directly from the financial institution. Ocrolus digitizes bank and credit card statements from all US financial institutions to help lenders digitize their data collection for cash-flow analysis. With the Plaid + Ocrolus integration, your users can verify their accounts in seconds by inputting their banking credentials in Plaid's front-end module. Plaid will retrieve the relevant bank information and pass it to Ocrolus for further digestion and reporting in a seamless, secure fashion. Plaid's mobile-friendly module handles input validation, error handling, and multi-factor authentication, providing a seamless onboarding experience to convert more users for your business. #### Getting started  You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/docs/link/index.html.md) , a drop-in integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to create or be an existing [Ocrolus customer](https://www.ocrolus.com/get-api-keys/) in order to add a bank account. Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment and verification of assets. From there, you'll receive a Plaid `access_token`, which you can use generate an Ocrolus `processor_token` and/or `audit_copy_token`, depending on your use case, which allow you to quickly and securely verify banking information via the [Ocrolus API](https://www.ocrolus.com/) without having to store that sensitive information yourself. #### Instructions  ##### Set up your Plaid and Ocrolus accounts  You'll need accounts at both Plaid and Ocrolus in order to use the Plaid + Ocrolus integration. You'll also need to enable your Plaid account for the Ocrolus integration. First, you will need to work with the Ocrolus team to [sign up for an Ocrolus account](https://www.ocrolus.com/get-api-keys/) , if you do not already have one. Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup/ocrolus) . Your account will be automatically enabled for integration access. To verify that your Plaid account is enabled for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Ocrolus to enable the integration. ##### Create a link\_token  In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. View the [documentation](https://plaid.com/docs/api/link/index.html.md#linktokencreate) for a full list of `link_token` configurations. To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) . ```node app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['assets'], language: 'en', webhook: 'https://webhook.example.com', redirect_uri: 'https://domainname.com/oauth-page.html', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "products": ["assets"], "country_codes": ["US"], "language": "en", "webhook": "https://webhook.example.com", "redirect_uri": "https://domainname.com/oauth-page.html" }' ``` ```ruby post '/api/create_link_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: client_user_id }, client_name: 'Plaid Test App', products: ['assets'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.example.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.Products; import com.plaid.client.model.CountryCode; import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; public class PlaidExample { ... static class GetLinkToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.fromValue("assets"))) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .redirectUri("https://domainname.com/oauth-page.html") .webhook("https://webhook.example.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.link_token_create_request import LinkTokenCreateRequest from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser from plaid.model.products import Products from plaid.model.country_code import CountryCode @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( products=[Products("assets")], client_name="Plaid Test App", country_codes=[CountryCode('US')], redirect_uri='https://domainname.com/oauth-page.html', language='en', webhook='https://webhook.example.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetRedirectUri("https://domainname.com/oauth-page.html") request.SetProducts([]plaid.Products{plaid.PRODUCTS_ASSETS}) resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` ##### Integrate with Plaid Link  Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Ocrolus `processor_token`. Integrate Link ```javascript ``` See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations. `Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe. ##### Write server-side handler  The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint. Once you have the `access_token` for the Item, you can create an Ocrolus `processor_token` and/or `audit_copy_token`. You'll send these tokens to Ocrolus and they will use them to securely retrieve banking information from Plaid. ```node const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest, AssetReportAuditCopyCreateRequest, } = require('plaid'); // Change sandbox to production to test with live users or to go live! const configuration = new Configuration({ basePath: PlaidEnvironments[process.env.PLAID_ENV], baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, 'Plaid-Version': '2020-09-14', }, }, }); const plaidClient = new PlaidApi(configuration); try { // Exchange the public_token from Plaid Link for an access token. const tokenResponse = await plaidClient.itemPublicTokenExchange({ public_token: PUBLIC_TOKEN, }); const accessToken = tokenResponse.data.access_token; // Create a processor token for a specific account id. const request: ProcessorTokenCreateRequest = { access_token: accessToken, account_id: accountID, processor: 'ocrolus', }; const processorTokenResponse = await plaidClient.processorTokenCreate( request, ); const processorToken = processorTokenResponse.data.processor_token; // Create an Asset Report for the specific access token. const request: AssetReportCreateRequest = { access_tokens: [accessToken], days_requested: 90, options: {}, }; const response = await plaidClient.assetReportCreate(request); const assetReportId = response.data.asset_report_id; const assetReportToken = response.data.asset_report_token; // Create an audit copy token for the Asset Report. const auditCopyRequest: AssetReportAuditCopyCreateRequest = { asset_report_token: response.data.asset_report_token, auditor_id: 'ocrolus', }; const auditCopyResponse = await plaidClient.assetReportAuditCopyCreate(auditCopyRequest); const auditCopyToken = auditCopyResponse.data.audit_copy_token; } catch (error) { // handle error } ``` ```bash # Exchange the public token from Plaid Link for an access token. curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "${PUBLIC_TOKEN}" }' \ -X POST \ https://sandbox.plaid.com/item/public_token/exchange # Create a processor token for a specific account id. curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}", "account_id": "${ACCOUNT_ID}", "processor": "ocrolus" }' \ -X POST \ https://sandbox.plaid.com/processor/token/create # Create an Asset Report for the specific access token. curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_tokens": ["${ACCESS_TOKEN}"], "days_requested": 90, }' \ -X POST \ https://sandbox.plaid.com/asset_report/create # Create an audit copy token for the Asset Report. curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "asset_report_token": "${ASSET_REPORT_TOKEN}", "auditor_id": "ocrolus" }' \ -X POST \ https://sandbox.plaid.com/asset_report/audit_copy/create ``` ```ruby require 'plaid' # Change sandbox to production to test with live users or to go live! configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] configuration.api_key['Plaid-Version'] = '2020-09-14' api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) # Exchange the public token from Plaid Link for an access token. item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: public_token } ) exchange_token_response = client.item_public_token_exchange(item_public_token_exchange_request) access_token = exchange_token_response.access_token # Create a processor token for a specific account id. processor_token_create_request = Plaid::ProcessorTokenCreateRequest.new( { access_token: access_token, account_id: account_id, processor: "ocrolus" } ) create_response = client.processor_token_create(processor_token_create_request) processor_token = create_response.processor_token # Create an Asset Report for the specific access token. options = { client_report_id: '123', webhook: 'https://www.example.com', user: { client_user_id: '7f57eb3d2a9j6480121fx361', first_name: 'Jane', middle_name: 'Leah', last_name: 'Doe', ssn: '123-45-6789', phone_number: '(555) 123-4567', email: 'jane.doe@example.com', }, } request = Plaid::AssetReportCreateRequest.new( { access_tokens: [access_token], days_requested: 90, options: options } ) response = client.asset_report_create(request) asset_report_id = response.asset_report_id asset_report_token = response.asset_report_token # Create an audit copy token for the Asset Report. request = Plaid::AssetReportAuditCopyCreateRequest.new( { asset_report_token: asset_report_token, auditor_id: 'ocrolus' } ) response = client.asset_report_audit_copy_create(request) audit_copy_token = response.audit_copy_token ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; import com.plaid.client.model.ProcessorTokenCreateRequest; import com.plaid.client.model.ProcessorTokenCreateResponse; import com.plaid.client.model.AssetReportCreateRequest; import com.plaid.client.model.AssetReportUser; import com.plaid.client.model.AssetReportCreateRequestOptions; import com.plaid.client.model.AssetReportCreateResponse; import com.plaid.client.model.AssetReportAuditCopyCreateRequest; import com.plaid.client.model.AssetReportAuditCopyCreateResponse; // Change sandbox to production to test with live users or to go live! HashMap apiKeys = new HashMap(); apiKeys.put("clientId", plaidClientId); apiKeys.put("secret", plaidSecret); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange the public token from Plaid Link for an access token. ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response exchangeResponse = client() .itemPublicTokenExchange(request) .execute(); // Create a processor token for a specific account id. if (exchangeResponse.isSuccessful()) { String accessToken = exchangeResponse.body().getAccessToken(); ProcessorTokenCreateRequest request = new ProcessorTokenCreateRequest() .accessToken(accessToken) .processor("ocrolus") .accountId("FooBarAccountId"); Response response = client() .processorTokenCreate(request) .execute(); if (response.isSuccessful()) { String processorToken = response.body().getProcessorToken(); } } // Create an Asset Report for the specific access token. AssetReportCreateRequest assetReportCreateRequest = new AssetReportCreateRequest() .accessTokens(accessTokens) .daysRequested(90); AssetReportUser assetReportUser = new AssetReportUser() .firstName("Alberta") .middleName("Bobbeth") .lastName("Charleson"); AssetReportCreateRequestOptions assetReportCreateOptions = new AssetReportCreateRequestOptions() .user(assetReportUser) .webhook(webhookUrl); assetReportCreateRequest.options(assetReportCreateOptions); Response response = client .assetReportCreate(assetReportCreateRequest) .execute(); String assetReportId = response.body().getAssetReportId(); String assetReportToken = response.body().getAssetReportToken(); // Create an audit copy token for the Asset Report. AssetReportAuditCopyCreateRequest request = new AssetReportAuditCopyCreateRequest() .assetReportToken(assetReportToken) .auditorId("ocrolus"); Response response = client().assetReportAuditCopyCreate(request).execute(); String auditCopyToken = response.body().getAuditCopyToken(); ``` ```python import plaid from plaid.api import plaid_api from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest from plaid.model.processor_token_create_request import ProcessorTokenCreateRequest from plaid.model.asset_report_create_request import AssetReportCreateRequest from plaid.model.asset_report_audit_copy_create_request import AssetReportAuditCopyCreateRequest # Change sandbox to production to test with live users or to go live! configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, 'plaidVersion': '2020-09-14' } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Exchange the public token from Plaid Link for an access token. exchange_request = ItemPublicTokenExchangeRequest(public_token=public_token) exchange_token_response = client.item_public_token_exchange(exchange_request) access_token = exchange_token_response['access_token'] # Create a processor token for a specific account id. create_request = ProcessorTokenCreateRequest( access_token=access_token, account_id=account_id, processor="" ) create_response = client.processor_token_create(create_request) processor_token = create_response['processor_token'] # Create an Asset Report for the specific access token. request = AssetReportCreateRequest( access_tokens=[access_token], days_requested=90, options=AssetReportCreateRequestOptions( webhook='https://www.example.com', client_report_id='123', user=AssetReportUser( client_user_id='7f57eb3d2a9j6480121fx361', first_name='Jane', middle_name='Leah', last_name='Doe', ssn='123-45-6789', phone_number='(555) 123-4567', email='jane.doe@example.com', ) ) ) response = client.asset_report_create(request) asset_report_id = response['asset_report_id'] asset_report_token = response['asset_report_token'] # Create an audit copy token for the Asset Report. request = AssetReportAuditCopyCreateRequest( asset_report_token=asset_report_token, auditor_id='ocrolus' ) response = client.asset_report_audit_copy_create(request) audit_copy_token = response['audit_copy_token'] ``` ```go import ( "context" "os" plaid "github.com/plaid/plaid-go/v40/plaid" ) // create the client configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) // exchange the public_token for an access_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest("PUBLIC_TOKEN"), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() // get the account id accountsResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest(plaid.AccountsGetRequest{ AccessToken: accessToken, }).Execute() accountID := accountsResp.GetAccounts()[0].GetAccountId() // create a processor token for the specific account id ocrolusTokenResp, _, err := client.PlaidApi.ProcessorTokenCreate(ctx).ProcessorTokenCreateRequest( *plaid.NewProcessorTokenCreateRequest(accessToken, accountID, "ocrolus"), ).Execute() // create an asset report assetReportCreateResp, _, err := client.PlaidApi.AssetReportCreate(ctx).AssetReportCreateRequest( *plaid.NewAssetReportCreateRequest([]string{accessToken}, 20), ).Execute() assetReportToken := assetReportCreateResp.GetAssetReportToken() // create an audit copy token for the Asset Report. auditCopyCreateRequest := plaid.NewAssetReportAuditCopyCreateRequest(assetReportToken, CLIENT_ID) auditCopyCreateResponse, _, err := client.PlaidApi.AssetReportAuditCopyCreate(ctx).AssetReportAuditCopyCreateRequest(*auditCopyCreateRequest).Execute() auditCopyToken := auditCopyCreateResponse.GetAuditCopyToken() ``` For a valid request, the API will return a JSON response similar to: ```json { "processor_token": "processor-sandbox-0asd1-a92nc", "request_id": "UNIQUE_REQUEST_ID" } ``` For a valid `audit_copy_token` request, the API will return a JSON response similar to: ```json { "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4", "request_id": "UNIQUE_REQUEST_ID" } ``` For more information on creating Asset Report `audit_copy_tokens`, see the documentation for the [Assets](https://plaid.com/docs/assets/index.html.md) product. ##### Testing your Ocrolus integration  You can create Ocrolus `processor_tokens` in Sandbox (sandbox.plaid.com, allows testing with simulated users). To test the integration in Sandbox mode, use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) when launching Link with a `link_token` created in the Sandbox environment. To move to Production, [request access](https://dashboard.plaid.com/settings/team/products) from the Dashboard. You will want to ensure that you have valid Ocrolus Production credentials prior to connecting bank accounts in the Ocrolus API with Plaid. #### Support and questions  Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) . If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can. --- # Auth - Add Auth to your app | Plaid Docs Add Auth to your app  ===================== #### Use Auth to connect user bank accounts  In this guide, we'll demonstrate how to add [Auth](https://plaid.com/docs/api/products/auth/index.html.md) to your app so that you can connect to your users' bank accounts and obtain the information needed to set up funds transfers. If you're already familiar with using Plaid and are set up to make calls to the Plaid API, see [Getting Auth data](https://plaid.com/docs/auth/add-to-app/index.html.md#getting-auth-data) . If you're interested in using a Plaid partner, such as Stripe or Dwolla, to process payments, see [Moving funds with a payment partner](https://plaid.com/docs/auth/add-to-app/index.html.md#moving-funds-with-a-payment-partner) . Prefer to learn by watching? A [video guide](https://youtu.be/FlZ5nzlIq74) is available for this topic. #### Get Plaid API keys and complete application and company profile  If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard. You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile and company profile must be completed before connecting to certain institutions in Production. #### Install and initialize Plaid libraries  You can use our official server-side client libraries to connect to the Plaid API from your application: ```node // Install via npm npm install --save plaid ``` ```bash ## Not applicable with curl calls ``` ```ruby # Available as a gem gem install plaid ``` ```java /* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ implementation "com.plaid:plaid-java:{VERSION}" /* For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ com.plaid plaid-java {VERSION} ``` ```python # Install through pip, only supports Python 3 pip install --upgrade plaid-python ``` ```go go get github.com/plaid/plaid-go ``` After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls. ```node // Using Express const express = require('express'); const app = express(); app.use(express.json()); const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const client = new PlaidApi(configuration); ``` ```bash ## Not applicable with curl calls ``` ```ruby require 'sinatra' require 'plaid' set :port, ENV['APP_PORT'] || 8000 configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) ``` ```java import java.net.*; import java.io.*; import retrofit2.Response; import java.util.Arrays; import com.sun.net.httpserver.*; import com.plaid.client.ApiClient; import com.plaid.client.request.PlaidApi; public class PlaidExample { private static final String CLIENT_ID = System.getenv("PLAID_CLIENT_ID"); private static final String SECRET = System.getenv("PLAID_SECRET"); public static void main(String[] args) { HttpServer server = HttpServer.create( new InetSocketAddress("localhost", 8000), 0); server.createContext("/create_link_token", new GetLinkToken()); server.setExecutor(null); server.start(); } // Additional server code goes here } ``` ```python import plaid from plaid.api import plaid_api from flask import Flask from flask import render_template from flask import request from flask import jsonify app = Flask(name) configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Additional server code goes here if __name__ == "__main__": app.run(port=8000) ``` ```go import ( "context" "net/http" "os" "github.com/gin-gonic/gin" "github.com/plaid/plaid-go/v3/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) func main() { r := gin.Default() // Server endpoints would be declared here // e.g. r.POST("/create_link_token", createLinkToken) r.POST("/create_link_token", createLinkToken) err := r.Run(":8000") if err != nil { panic("unable to start server") } } ``` #### Create an Item using Link  These instructions cover Link for web applications. For instructions on using Link in mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . Plaid Link is the client-side component that your users interact with to securely connect their bank accounts to your app. An [Item](https://plaid.com/docs/quickstart/glossary/index.html.md#item) is created when a user successfully logs into their financial institution using Link. An Item represents a single login at a financial institution. Items do not represent individual bank accounts, although all bank accounts are associated with an Item. For example, if a user has a single login at a bank that allows them to access both a checking account and a savings account, only a single Item would be associated with both of the accounts. When using Auth, you will typically only need access to the specific bank account that will be used to transfer funds, rather than all of the accounts a user may have at an institution. Because of this, it is recommended that you configure Link with [Account Select](https://plaid.com/docs/link/customization/index.html.md#account-select) when using Auth. Configuring Link with Account Select will limit unnecessary access to user accounts. You can [enable Account Select from the Dashboard](https://dashboard.plaid.com/link/account-select) . To create an Item, you'll first need to create a [Link token](https://plaid.com/docs/quickstart/glossary/index.html.md#link-token) on your application server. You can create a Link token by calling the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client-side of your application, you'll initialize Link with using the Link token you created. The code samples below demonstrate how to create a Link token and how to initialize Link using the token. ##### Create a Link token  ```node app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['auth'], language: 'en', webhook: 'https://webhook.example.com', redirect_uri: 'https://domainname.com/oauth-page.html', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "products": ["auth"], "country_codes": ["US"], "language": "en", "webhook": "https://webhook.example.com", "redirect_uri": "https://domainname.com/oauth-page.html" }' ``` ```ruby post '/api/create_link_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: client_user_id }, client_name: 'Plaid Test App', products: ['auth'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.example.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.Products; import com.plaid.client.model.CountryCode; import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; public class PlaidExample { ... static class GetLinkToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.fromValue("auth"))) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .redirectUri("https://domainname.com/oauth-page.html") .webhook("https://webhook.example.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.link_token_create_request import LinkTokenCreateRequest from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser from plaid.model.products import Products from plaid.model.country_code import CountryCode @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( products=[Products("auth")], client_name="Plaid Test App", country_codes=[CountryCode('US')], redirect_uri='https://domainname.com/oauth-page.html', language='en', webhook='https://webhook.example.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetRedirectUri("https://domainname.com/oauth-page.html") request.SetProducts([]plaid.Products{plaid.PRODUCTS_AUTH}) resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` ##### Initialize Link with the Link token  If your use case involves a pay-by-bank payments flow where the end user can choose between paying via a credit card and paying via a bank account, it is highly recommended to use the [Embedded experience](https://plaid.com/docs/link/embedded-institution-search/index.html.md) for Link to increase uptake of pay-by-bank. If your use case is an account opening or funding flow that requires the customer to use a bank account, or has a surcharge for credit card use, use the standard Link experience. Select group for content switcher Account funding (standard Link)Pay by Bank (Embedded Link) app.js ```javascript const handler = Plaid.create({ token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Upon successful linking of a bank account, // Link will return a public token. // Exchange the public token for an access token // to make calls to the Plaid API. $.post('/exchange_public_token', { public_token: public_token, }); }, onLoad: () => {}, onExit: (err, metadata) => { // Optionally capture when your user exited the Link flow. // Storing this information can be helpful for support. }, onEvent: (eventName, metadata) => { // Optionally capture Link flow events, streamed through // this callback as your users connect an Item to Plaid. }, }); handler.open(); ``` The sample code below is for JavaScript. For more examples for other platforms, see [Embedded Link](https://plaid.com/docs/link/embedded-institution-search/index.html.md#integration-steps) . Embedded Institution search - web (HTML) ```html ``` Embedded Institution Search - web (JavaScript) ```javascript // The container at `#plaid-embedded-link-container` will need to be sized in order to // control the size of the embedded Plaid module const embeddedLinkOpenTarget = document.querySelector('#plaid-embedded-link-container'); Plaid.createEmbedded( { token: 'GENERATED_LINK_TOKEN', onSuccess: (public_token, metadata) => {}, onLoad: () => {}, onExit: (err, metadata) => {}, onEvent: (eventName, metadata) => {}, }, embeddedLinkOpenTarget, ); ``` #### Obtain an access token  When a user successfully links an Item via Link, the [onSuccess](https://plaid.com/docs/link/web/index.html.md#onsuccess) callback will be called. The `onSuccess` callback returns a [public token](https://plaid.com/docs/quickstart/glossary/index.html.md#public-token) . On your application server, exchange the public token for an [access token](https://plaid.com/docs/quickstart/glossary/index.html.md#access-token) and an [Item ID](https://plaid.com/docs/quickstart/glossary/index.html.md#item-id) by calling `/item/public_token/exchange/`. The access token will allow you to make authenticated calls to the Plaid API. Store the access token and Item ID in a secure datastore, as they're used to access Item data and identify webhooks, respectively. The access token will remain valid unless you actively expire it via rotation or remove it by calling [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) on the corresponding Item. For security purposes, never store the access token in client-side code. The public token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it. ##### Exchange public token for an access token  ```node app.post('/api/exchange_public_token', async function ( request, response, next, ) { const publicToken = request.body.public_token; try { const tokenResponse = await client.itemPublicTokenExchange({ public_token: publicToken, }); // These values should be saved to a persistent database and // associated with the currently signed-in user const accessToken = tokenResponse.data.access_token; const itemID = tokenResponse.data.item_id; response.json({ public_token_exchange: 'complete' }); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-12345678-abcd-1234-abcd-1234567890ab" }' ``` ```ruby access_token = nil post '/api/exchange_public_token' do request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: params["public_token"] } ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response.access_token item_id = response.item_id content_type :json {public_token_exchange: "complete"}.to_json end ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; public class PlaidExample { ... static class GetAccessToken implements HttpHandler { private static PlaidClient plaidClient; private String publicToken; private String accessToken; private String itemId; public void handle(HttpExchange t) throws IOException { // Simplified pseudo-code for obtaining public_token InputStream is = t.getRequestBody(); publicToken = is.publicToken(); // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange public_token for an access_token ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response response = plaidClient .itemPublicTokenExchange(request) .execute(); // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken = response.body().getAccessToken(); itemId = response.body().getItemId(); String message = "{\"public_token_exchange\": \"complete\"}"; return Response .status(Response.Status.OK) .entity(message) .type(MediaType.APPLICATION_JSON) } } } ``` ```python access_token = None item_id = None @app.route('/exchange_public_token', methods=['POST']) def exchange_public_token(): global access_token public_token = request.form['public_token'] request = ItemPublicTokenExchangeRequest( public_token=public_token ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response['access_token'] item_id = response['item_id'] return jsonify({'public_token_exchange': 'complete'}) ``` ```go func getAccessToken(c *gin.Context) { ctx := context.Background() publicToken := c.PostForm("public_token") // exchange the public_token for an access_token exchangePublicTokenReq := plaid.NewItemPublicTokenExchangeRequest(publicToken) exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *exchangePublicTokenReq, ).Execute() // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken := exchangePublicTokenResp.GetAccessToken() itemID := exchangePublicTokenResp.GetItemId() c.JSON(http.StatusOK, gin.H{"public_token_exchange": "complete"}) } ``` #### Getting Auth data  Now that you have an access token, you can begin making authenticated calls to the Plaid API. If you are processing payments yourself, the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) endpoint to retrieve the bank account and bank identification numbers (such as routing numbers, for US accounts) associated with an Item's accounts. You can then supply these to your payment system. If you are using a Plaid partner to move funds, you will not need to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) . Instead, see [Moving funds with a payment partner](https://plaid.com/docs/auth/add-to-app/index.html.md#moving-funds-with-a-payment-partner) . ```node const { AuthGetRequest } = require('plaid'); // Call /auth/get and retrieve account numbers for an Item const request = { access_token: access_token, }; try { const response = await plaidClient.authGet(request); const accountData = response.data.accounts; if (response.data.numbers.ach.length > 0) { // Handle ACH numbers (US accounts) const achNumbers = response.data.numbers.ach; } if (response.data.numbers.eft.length > 0) { // Handle EFT numbers (Canadian accounts) const eftNumbers = response.data.numbers.eft; } if (response.data.numbers.international.length > 0) { // Handle International numbers const internationalNumbers = response.data.numbers.international; } if (response.data.numbers.bacs.length > 0) { // Handle BACS numbers (British accounts) const bacsNumbers = response.data.numbers.bacs; } } catch (error) { //handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/auth/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```ruby require 'plaid' # Call /auth/get and retrieve account numbers for an Item request = Plaid::AuthGetRequest.new({ access_token: access_token }) response = client.auth_get(request) numbers = response.numbers if numbers.ach.length > 0 # Handle ACH numbers (US accounts) achNumbers = numbers.ach end if numbers.eft.length > 0 # Handle EFT numbers (Canadian accounts) eftNumbers = numbers.eft end if numbers.international.length > 0 # Handle International numbers (Standard International accounts) internationalNumbers = numbers.international end if numbers.bacs.length > 0 # Handle BACS numbers (British accounts) bacsNumbers = numbers.bacs end ``` ```java import com.plaid.client.model.AuthGetRequest; import com.plaid.client.model.AuthGetResponse; // Call /auth/get and retrieve account numbers for an Item AuthGetRequest request = new AuthGetRequest() .accessToken(accessToken); Response response = client() .authGet(request) .execute(); if (response.body().getNumbers().getACH().size() > 0) { // Handle ACH numbers (US accounts) for (AuthGetResponse.NumberACH numberACH : response.body().getNumbers().getACH()) { ... } } if (response.body().getNumbers().getEFT().size() > 0) { // Handle EFT numbers (Canadian accounts) for (AuthGetResponse.NumberEFT numberEFT : response.body().getNumbers().getEFT()) { ... } } if (response.body().getNumbers().getInternational().size() > 0) { // Handle International numbers (Standard International accounts) for (AuthGetResponse.NumberInternational numberInternational : response.body().getNumbers().getInternational()) { ... } } if (response.body().getNumbers().getBACS().size() > 0) { // Handle BACS numbers (British accounts) for (AuthGetResponse.NumberBACS numberBACS : response.body().getNumbers().getBACS()) { ... } } ``` ```python import plaid from plaid.model.auth_get_request import AuthGetRequest # Call /auth/get and retrieve account numbers for an Item request = AuthGetRequest(access_token=access_token) response = client.auth_get(request) numbers = response['numbers'] if len(numbers['ach']) > 0: # Handle ACH numbers (US accounts) achNumbers = numbers['ach'] if len(numbers['eft']) > 0: # Handle EFT numbers (Canadian accounts) eftNumbers = numbers['eft'] if len(numbers['international']) > 0: # Handle International numbers (Standard International accounts) internationalNumbers = numbers['international'] if len(numbers['bacs']) > 0: # Handle BACS numbers (British accounts) bacsNumbers = numbers['bacs'] ``` ```go import ( "context" "github.com/plaid/plaid-go/v40/plaid" ) // Call /auth/get and retrieve account numbers for an Item authGetResp, _, err := client.PlaidApi.AuthGet(ctx).AuthGetRequest( *plaid.NewAuthGetRequest(accessToken), ).Execute() numbers := authGetResp.GetNumbers() ``` Example response data is below. Note that this is test account data; real accounts would not include all four sets of numbers. /auth/get sample response ```json { "accounts": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "balances": { "available": 100, "current": 110, "limit": null, "iso_currency_code": "USD", "unofficial_currency_code": null }, "mask": "9606", "name": "Plaid Checking", "official_name": "Plaid Gold Checking", "subtype": "checking", "type": "depository" } ], "numbers": { "ach": [ { "account": "9900009606", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "routing": "011401533", "wire_routing": "021000021" } ], "eft": [ { "account": "111122223333", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "institution": "021", "branch": "01140" } ], "international": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "bic": "NWBKGB21", "iban": "GB29NWBK60161331926819" } ], "bacs": [ { "account": "31926819", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "sort_code": "601613" } ] }, "item": { "available_products": [ "balance", "identity", "payment_initiation", "transactions" ], "billed_products": ["assets", "auth"], "consent_expiration_time": null, "error": null, "institution_id": "ins_117650", "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6", "webhook": "https://www.genericwebhookurl.com/webhook" }, "request_id": "m8MDnv9okwxFNBV" } ``` #### Moving funds with a payment partner  You can move money via ACH transfer by pairing Auth with one of Plaid's payment partners. When using a partner to move money, the partner's payments service will initiate the transfer; Plaid does not function as the payment processor. For the full list of payments platforms who have partnered with Plaid to provide ACH money movement, see [Auth Partnerships](https://plaid.com/docs/auth/partnerships/index.html.md) . To move money using a Plaid partner, first create an Item using Link and obtain an access token as described above. Then, instead of calling Plaid's Auth endpoints, call one of Plaid's [processor token endpoints](https://plaid.com/docs/api/processors/index.html.md) to create a processor token. You can then send this processor token to one of Plaid's partners by using endpoints that are specific to the payment platform. Refer to the partner's technical documentation for more information. Using a partner to transfer funds gives you access to payment functionality while freeing you from having to securely store sensitive bank account information. The sample code below demonstrates a call to [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) using Dwolla as the payment processor. ```bash # Create a processor token for a specific account id. curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}", "account_id": "${ACCOUNT_ID}", "processor": "dwolla" }' \ -X POST \ https://sandbox.plaid.com/processor/token/create ``` ```java import com.plaid.client.model.ProcessorTokenCreateRequest; import com.plaid.client.model.ProcessorTokenCreateResponse; // Create a processor token for a specific account id ProcessorTokenCreateRequest request = new ProcessorTokenCreateRequest() .accessToken(accessToken) .processor("dwolla") .accountId("ACCOUNT_ID"); Response dwollaResponse = client() .processorTokenCreate(request) .execute(); String dwollaProcessorToken = dwollaResponse.body().getProcessorToken(); ``` ```ruby require 'plaid' # Create a processor token for a specific account id processor_token_create_request = Plaid::ProcessorTokenCreateRequest.new({ access_token: access_token, account_id: account_id, processor: "dwolla" } ) create_response = client.processor_token_create(processor_token_create_request) processor_token = create_response.processor_token ``` ```python from plaid.model.processor_token_create_request import ProcessorTokenCreateRequest # Create a processor token for a specific account id create_request = ProcessorTokenCreateRequest( access_token=access_token, account_id=account_id, processor='dwolla' ) create_response = client.processor_token_create(create_request) processor_token = create_response['processor_token'] ``` ```node const { ProcessorTokenCreateRequest } = require('plaid'); try { // Create a processor token for a specific account id const request: ProcessorTokenCreateRequest = { access_token: accessToken, account_id: accountID, processor: 'dwolla', }; const processorTokenResponse = await plaidClient.processorTokenCreate( request, ); const processorToken = processorTokenResponse.data.processor_token; } catch (error) { // handle error } ``` ```go import ( "context" "os" plaid "github.com/plaid/plaid-go/v40/plaid" ) // Get the account id accountsResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest(plaid.AccountsGetRequest{ AccessToken: accessToken, }).Execute() accountID := accountsResp.GetAccounts()[0].GetAccountId() // Create a dwolla token for the specific account id request := plaid.NewProcessorTokenCreateRequest(accessToken, accountID, "dwolla") processorTokenResp, _, err := client.PlaidApi.ProcessorTokenCreate(ctx).ProcessorTokenCreateRequest( *request, ).Execute() ``` #### Tutorial and example code in Plaid Pattern  For a real-life example of an app that incorporates Auth, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that fetches Auth data in order to set up funds transfers. The Auth code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L81-L135) . For a step-by-step tutorial on how to implement account funding, [Account funding tutorial](https://github.com/plaid/account-funding-tutorial) . #### Next steps  Once Auth is implemented in your app, see [Micro-deposit and database verification](https://plaid.com/docs/auth/coverage/index.html.md) to make sure your app is supporting the maximum number of institutions and verification methods (US only). If your use case is an account funding use case, see [the Account funding solutions guide](https://plaid.com/documents/plaid-account-funding-guide.pdf) for a set of recommendations on how to implement Auth. If you're ready to launch to Production, see the Launch checklist. #### Launch checklist  Recommended steps to take before launching in Production [Launch](https://plaid.com/docs/launch-checklist/index.html.md) --- # Auth - Automated Micro-deposits | Plaid Docs Automated Micro-deposits  ========================= #### Learn how to authenticate your users in a secure and frictionless micro-deposit flow  #### The Automated Micro-deposit flow  The Automated Micro-deposits authentication flow is supported for an additional 1,900 financial institutions in the US where Instant Auth is not available, accounting for approximately <1% of depository accounts. Plaid will make a single micro-deposit and then automatically verify it within one to two business days. The user launches Link... (An image of "The user launches Link...") (An image of "...and selects the institution to link.") (An image of "They find their institution...") (An image of "...and log in.") (An image of "Next, they select the account to link. (Single-account select is typically recommended for Auth.)") (An image of "They verify their bank's routing and account numbers...") (An image of "...and their name.") (An image of "Plaid will send a micro-deposit. Once it lands, Plaid will automatically detect it and verify the account.") You can try out the Automated Micro-deposits flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=6) . See more details in our [testing guide](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-automated-micro-deposits) . A user connects their financial institution using the following connection flow: 1. Starting on a page in your app, the user clicks an action that opens Plaid Link, with the correct Auth [configuration](https://plaid.com/docs/auth/coverage/automated/index.html.md#configure--create-a-link_token) . 2. Inside of Plaid Link, the user selects their institution, authenticates with their credentials, provides their account and routing number, and enters in their legal name. 3. Upon [successful authentication](https://plaid.com/docs/auth/coverage/automated/index.html.md#exchange-the-public-token) , Link closes with a `public_token` and a `metadata` account status of `pending_automatic_verification`. 4. Behind the scenes, Plaid sends a single micro-deposit to the user's account and will automatically verify the deposited amounts within one to two business days. 5. When verification succeeds or fails, Plaid sends an [Auth webhook](https://plaid.com/docs/auth/coverage/automated/index.html.md#handle-auth-webhooks) , which you can use to notify the user that their account is ready to move money. Once this step is done, your user's Auth data is verified and [ready to fetch](https://plaid.com/docs/auth/coverage/automated/index.html.md#fetch-auth-data) . #### Configure & Create a link\_token  Create a `link_token` with the following parameters: * `products` array containing `auth` or `transfer` -- unlike with Same-Day Micro-deposits, you can also include other products besides `auth` or `transfer` when creating a Link token for use with Automated Micro-deposits, but `auth` or `transfer` must be present. * `country_codes` set to `['US']` – Micro-deposit verification is currently only available in the United States. * A `webhook` URL to receive a POST HTTPS request sent from Plaid's servers to your application server, after Automated Micro-deposits succeeds or fails verification of a user's micro-deposits. * `auth` object should specify `"automated_microdeposits_enabled": true` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user": {"client_user_id": "${UNIQUE_USER_ID}"}, "client_name": "Plaid App", "products": ["auth"], "country_codes": ["US"], "language": "en", "webhook": "https://sample-web-hook.com", "auth": { "automated_microdeposits_enabled": true } }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: "user-id", }, client_name: 'Plaid Test App', products: ['auth'], country_codes: ['US'], language: "en", webhook: 'https://webhook.sample.com', link_customization_name: "default", auth: { automated_microdeposits_enabled: true, }, } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```node const request: LinkTokenCreateRequest = { user: { client_user_id: new Date().getTime().toString() }, client_name: 'Plaid App', products: [Products.Auth], country_codes: [CountryCode.Us], language: 'en', auth: { automated_microdeposits_enabled: true, }, }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```java LinkTokenCreateRequestAuth auth = new LinkTokenCreateRequestAuth() .automatedMicrodepositsEnabled(true); LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("very nice client name") .products(Arrays.asList(Products.AUTH)) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .webhook("https://example.com/webhook") .linkCustomizationName("default") .accountFilters(accountFilters) .auth(auth); ``` ```python request = LinkTokenCreateRequest( products=[Products('auth')], client_name="Plaid Test App", country_codes=[CountryCode('US')], language='en', webhook='https://sample-webhook-uri.com', link_customization_name='default', user=LinkTokenCreateRequestUser( client_user_id='user-id', ), auth=LinkTokenCreateRequestAuth( automated_microdeposits_enabled=True, ) ) response = client.link_token_create(request) ``` ```go user := plaid.LinkTokenCreateRequestUser{ ClientUserId: "user-id", } request := plaid.NewLinkTokenCreateRequest( "Plaid Test", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetProducts([]plaid.Products{plaid.PRODUCTS_AUTH}) request.SetLinkCustomizationName("default") request.SetWebhook("https://webhook-uri.com") var automatedMicrodepositsEnabled bool = true request.SetAuth(plaid.LinkTokenCreateRequestAuth{ AutomatedMicrodepositsEnabled: &automatedMicrodepositsEnabled, }) resp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := resp.GetLinkToken() ``` #### Initialize Link with a link\_token  After creating a `link_token` for the `auth` product, use it to initialize Plaid Link. When the user inputs their username and password, and account and routing numbers for the financial institution, the `onSuccess()` callback function will return a `public_token`, with `verification_status` equal to `'pending_automatic_verification'`. App.js ```javascript const linkHandler = Plaid.create({ // Fetch a link_token configured for 'auth' from your app server token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token and accounts to your app server $.post('/exchange_public_token', { publicToken: public_token, accounts: metadata.accounts, }); metadata = { ..., link_session_id: String, institution: { name: 'Bank of the West', institution_id: 'ins_100017' }, accounts: [{ id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D', mask: '1234', name: null, type: 'depository', subtype: 'checking', verification_status: 'pending_automatic_verification' }] } }, // ... }); // Open Link on user-action linkHandler.open(); ``` ##### Display a "pending" status in your app  Because Automated verification usually takes between one to two days to complete, we recommend displaying a UI in your app that communicates to a user that verification will occur automatically and is currently pending. You can use the `verification_status` key returned in the `onSuccess` `metadata.accounts` object once Plaid Link closes successfully. Metadata verification\_status ```javascript verification_status: 'pending_automatic_verification'; ``` You can also [fetch the verification\_status](https://plaid.com/docs/auth/coverage/automated/index.html.md#check-the-account-verification-status-optional) for an Item's account via the Plaid API to obtain the latest account status. #### Exchange the public token  In your own backend server, call the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint with the Link `public_token` received in the `onSuccess` callback to obtain an `access_token`. Persist the returned `access_token` and `item_id` in your database in relation to the user. Note that micro-deposits will only be delivered to the ACH network in the Production environment. To test your integration outside of Production, see [Testing automated micro-deposits in Sandbox](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-automated-micro-deposits) . ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" }' ``` ```node // publicToken and accountID are sent from your app to your backend-server const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D'; const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d'; // Obtain an access_token from the Link public_token try { const response = await client.itemPublicTokenExchange({ public_token: publicToken, }); const accessToken = response.data.access_token; } catch (err) { // handle error } ``` ```python # publicToken and accountID are sent from your app to your backend-server accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D' publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' # Obtain an access_token from the Link public_token token_request = ItemPublicTokenExchangeRequest( public_token=publicToken) token_response = client.item_public_token_exchange(token_request) accessToken = token_response['access_token'] ``` ```ruby # publicToken and accountID are sent from your app to your backend-server accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D' publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' # Obtain an access_token from the Link public_token item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: publicToken } ) token_response = client.item_public_token_exchange( item_public_token_exchange_request ) access_token = token_response.access_token ``` ```java // publicToken and accountID are sent from your app to your backend-servers String accountID = "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"; String publicToken = "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"; // Obtain an access_token from the Link public_token ItemPublicTokenExchangeRequest tokenRequest = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response tokenResponse = plaidClient .itemPublicTokenExchange(tokenRequest) .execute(); String accessToken = tokenResponse.body().getAccessToken(); ``` ```go // publicToken and accountID are sent from your app to your backend-server accountID := "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D" publicToken := "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" // Obtain an access_token from the Link public_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest(publicToken), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() ``` Exchange token response ```json { "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755", "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op", "request_id": "m8MDnv9okwxFNBV" } ``` #### Handle Auth webhooks  Before you can call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) to fetch Auth data for a user's `access_token`, a micro-deposit first need to post successfully to the user's bank account. Because Plaid uses Same Day ACH to send a single micro-deposit amount, this process usually takes between one to two days. Once the deposit has arrived in the user's account, Plaid will automatically verify the deposit transaction and send an [AUTOMATICALLY\_VERIFIED](https://plaid.com/docs/api/products/auth/index.html.md#automatically_verified) webhook to confirm the account and routing numbers have been successfully verified. Attempting to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) on an unverified `access_token` will result in a [PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/item/index.html.md#product_not_ready) error. Auth AUTOMATICALLY\_VERIFIED webhook ```json > POST https://your_app_url.com/webhook { "webhook_type": "AUTH", "webhook_code": "AUTOMATICALLY_VERIFIED", "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D" } ``` Occasionally automatic verification may fail, likely due to erroneous user input, such as an incorrect account and routing number pair. If the Item is unable to be verified within seven days, Plaid will send a [VERIFICATION\_EXPIRED](https://plaid.com/docs/api/products/auth/index.html.md#verification_expired) webhook. When verification fails, the Item is permanently locked; we recommend prompting your user to retry connecting their institution via Link. Auth VERIFICATION\_EXPIRED webhook ```json > POST https://your_app_url.com/webhook { "webhook_type": "AUTH", "webhook_code": "VERIFICATION_EXPIRED", "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm", "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D" } ``` If Plaid encounters an `ITEM_LOGIN_REQUIRED` error during attempted validation, this may mean that Plaid lost access to the user's account after sending this micro-deposit but before being able to verify it. If this occurs, send the user through the [update mode](https://plaid.com/docs/link/update-mode/index.html.md) flow to re-verify their account. The example code below shows how to handle `AUTOMATICALLY_VERIFIED` and `VERIFICATION_EXPIRED` webhooks and call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) to retrieve account and routing data. If you are using the Sandbox environment, you can use the [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) endpoint to test your integration. ```bash ## no curl example ``` ```node // This example uses Express to receive webhooks const app = require('express')(); const bodyParser = require('body-parser'); app.use(bodyParser); app.post('/webhook', async (request, response) => { const event = request.body; // Handle the event switch (event.webhook_code) { case 'AUTOMATICALLY_VERIFIED': const accessToken = lookupAccessToken(event.item_id); const request: AuthGetRequest = { access_token: accessToken }; const authResponse = await client.authGet(request); const numbers = authResponse.numbers; break; case 'VERIFICATION_EXPIRED': // handle verification failure; prompt user to re-authenticate console.error('Verification failed for', event.item_id); break; default: // Unexpected event type return response.status(400).end(); } // Return a response to acknowledge receipt of the event response.json({ received: true }); }); app.listen(8000, () => console.log('Running on port 8000')); ``` ```python # This example uses Django to receive webhooks import json from django.http import HttpResponse @csrf_exempt def webhook_view(request): event = json.loads(request.body) # Handle the event if event['webhook_code'] == 'AUTOMATICALLY_VERIFIED': access_token = lookup_access_token(event['item_id']); request = AuthGetRequest(access_token=access_token) auth_response = client.auth_get(request) numbers = auth_response['numbers'] elif event['webhook_code'] == 'VERIFICATION_EXPIRED': print('Verification failed for ', event['item_id']) # handle verification failure; prompt user to re-authenticate else: # Unexpected event type return HttpResponse(status=400) return HttpResponse(status=200) ``` ```ruby # Using Sinatra require 'json' post '/webhook' do event = JSON.parse(request.body.read) # Handle the event case event['webhook_code'] when 'AUTOMATICALLY_VERIFIED' access_token = lookup_access_token(event['item_id']); request = Plaid::AuthGetRequest.new({ access_token: access_token }) response = client.auth_get(request) numbers = response.numbers when 'VERIFICATION_EXPIRED' puts "Verification failed for #{event['item_id']}" # Handle verification failure; prompt user to re-authenticate else # Unexpected event type status 400 return end status 200 end ``` ```java // No example implementation for Java ``` ```go // No example implementation for Go ``` #### Check the account verification status (optional)  In some cases you may want to implement logic to display the `verification_status` of an Item that is pending automated verification in your app. The [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) API endpoint allows you to query this information. For non-programmatic access to this information, you can use the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification/) . ```bash curl -X POST https://sandbox.plaid.com/accounts/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755" }' ``` ```node // Fetch the accountID and accessToken from your database const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D'; const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755'; const request: AccountsGetRequest = { access_token: accessToken, }; try { const response = await client.accountsGet(request); const account = response.data.accounts.find((a) => a.account_id === accountID); const verificationStatus = account.verification_status; } catch (err) { // handle error } ``` ```python # Fetch the accountID and accessToken from your database account_id = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D' access_token = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755' request = AccountsGetRequest(access_token=access_token) response = client.accounts_get(request) accounts = response['accounts'] ``` ```ruby # Fetch the accountID and accessToken from your database account_id = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D' access_token = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755' request = Plaid::AccountsGetRequest.new({ access_token: access_token }) response = client.accounts_get(request) accounts = response.accounts ``` ```java // Fetch the accountID and accessToken from your database String accountID = "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"; String accessToken = "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755"; AccountsGetRequest request = new AccountsGetRequest() .accessToken(accessToken); Response response = client() .accountsGet(request) .execute(); if (response.isSuccessful()) { AuthGetNumbers numbers = response.body().getNumbers(); } ``` ```go // Fetch the accountID and accessToken from your database accountID := "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D" accessToken := "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755" accountsGetResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest( *plaid.NewAccountsGetRequest(accessToken), ).Execute() accounts := accountsGetResp.GetAccounts() ``` Account get response ```json { "accounts": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "balances": { Object }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Checking", "type": "depository", "subtype": "checking", "verification_status": "pending_automatic_verification" | "automatically_verified" | "verification_expired" }, ... ], "item": { Object }, "request_id": String } ``` #### Fetch Auth data  Finally, we can retrieve Auth data once automated verification has succeeded: ```bash curl -X POST https://sandbox.plaid.com/auth/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755" }' ``` ```node const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755'; // Instantly fetch Auth numbers const request: AuthGetRequest = { access_token: accessToken, }; try { const response = await client.authGet(request); const numbers = response.data.numbers; } catch (err) { // handle error } ``` ```python access_token = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755' # Instantly fetch Auth numbers auth_request = AuthGetRequest(access_token=access_token) auth_response = client.auth_get(auth_request) numbers = auth_response['numbers'] ``` ```ruby access_token = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755'; # Instantly fetch Auth numbers request = Plaid::AuthGetRequest.new({ access_token: access_token }) auth_response = client.auth_get(request) numbers = auth_response.numbers ``` ```java String accessToken = "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755"; // Instantly fetch Auth numbers AuthGetRequest authGetRequest = new AuthGetRequest() .accessToken(accessToken); Response authResponse = client() .authGet(authGetRequest) .execute(); if (authResponse.isSuccessful()) { AuthGetResponse.Numbers numbers = authResponse.body().getNumbers(); } ``` ```go accessToken := "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755" // Instantly fetch Auth numbers authGetResp, _, err := client.PlaidApi.AuthGet(ctx).AuthGetRequest( *plaid.NewAuthGetRequest(accessToken), ).Execute() numbers := authGetResp.GetNumbers() ``` Auth response ```json { "numbers": { "ach": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "account": "1111222233330000", "routing": "011401533", "wire_routing": "021000021" } ], "eft": [], "international": [], "bacs": [] }, "accounts": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "balances": { Object }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "verification_status": "automatically_verified", "subtype": "checking" | "savings", "type": "depository" } ], "item": { Object }, "request_id": "m8MDnv9okwxFNBV" } ``` Check out the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) API reference documentation to see the full Auth request and response schema. #### Handling Link events  For a user who goes through the Automated Micro-deposit flow, the `TRANSITION_VIEW (view_name = NUMBERS)` event will occur after `SUBMIT_CREDENTIALS`, and in the `onSuccess` callback the `verification_status` will be `pending_automatic_verification`. Sample Link events for Automated Micro-deposits flow ```bash OPEN (view_name = CONSENT) TRANSITION_VIEW (view_name = SELECT_INSTITUTION) SEARCH_INSTITUTION SELECT_INSTITUTION TRANSITION_VIEW (view_name = CREDENTIAL) SUBMIT_CREDENTIALS TRANSITION_VIEW (view_name = LOADING) TRANSITION_VIEW (view_name = MFA, mfa_type = code) SUBMIT_MFA (mfa_type = code) TRANSITION_VIEW (view_name = LOADING) TRANSITION_VIEW (view_name = SELECT_ACCOUNT) TRANSITION_VIEW (view_name = NUMBERS) TRANSITION_VIEW (view_name = LOADING) TRANSITION_VIEW (view_name = CONNECTED) HANDOFF onSuccess (verification_status: pending_automatic_verification) ``` #### Same Day Micro-deposits  Integrate the manual micro-deposit method [View guide](https://plaid.com/docs/auth/coverage/same-day/index.html.md) #### Testing in Sandbox  Learn how to test each Auth method in the Sandbox [View guide](https://plaid.com/docs/auth/coverage/testing/index.html.md) --- # Auth - Database Auth | Plaid Docs Database Auth  ============== #### Evaluate a manually entered account using Plaid network data   #### Overview  Database Auth can increase conversion by providing instant account verification when end users cannot, or do not want to, log into their financial institution to verify their account. Examples include end users at banks that are not supported by Plaid, or users who need to verify a business bank account but who don't have access to manage the account via online banking. With Database Auth, users can instead enter their account and routing number manually. (An image of "Link flow. First screen shows Plaid consent pane, second screen shows radio toggle option to connect bank instantly (recommended) or manually, manually option is selected. Third screen shows a form where user can enter account details: account and routing number, owner name, and checking or savings.") Example Link flow with Database Auth Database Auth verifies account and routing numbers by checking the information provided against Plaid's known account numbers, leveraging Plaid's database of over 200 million verified accounts. If no match is found, Plaid will check the account number format against known usages by the institution associated with the given routing number. Database Auth will provide a verification status of 'pass', 'pass with caution', or 'fail' and a set of attributes that contributed to that status, such as whether a match was found or whether Plaid fell back to checking account number formats. Database Auth does not verify that the user has access to the bank account and does also not fully guarantee that the account exists. Database Auth does not create a live connection to the bank account and cannot be used to check real-time balances (although it is compatible with anti-risk products such as Signal and Identity Match). For these reasons, Database Auth should not be enabled where there is a very high risk of fraud or ACH returns. You can try out the Database Auth flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=7) . ##### Geographic availability  Database Auth is available in the United States and Canada. In Canada, Database Auth is in early availability. To request that your client be enabled for Database Auth in Canada, contact your account manager. In Canada only, Database Auth cannot be managed via the Account Verification Dashboard, and must instead be enabled by passing `auth.database_insights_enabled: true` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. ##### Database Auth flow  1. Starting on a page in your app, the user clicks an action that opens Plaid Link. 2. Inside of Plaid Link, the user selects an option that triggers the manual verification flow. This could occur because the user opted in to the manual flow (if Auth Type Select is enabled) or because their institution does not support Instant Auth. 3. The user will be prompted to enter their name, routing number, and account number. 4. Based on rules you have configured, the user will either see a success screen or a failure screen, or be prompted to fall back to micro-deposit-based verification. #### Implementation steps  1. Create a `link_token` with the following parameters: * The `products` array should include `auth` or `transfer` only, and no other products. * If you are enabling Identity Match, put `identity` in the `required_if_supported_products` array, as putting it in the `products` array will prevent Database Auth from activating. Approximately one-third of all Items verified via Database Auth are compatible with Identity Match. * If you plan to use Signal Transaction Scores, put `signal` in the `additional_consented_products` or `required_if_supported_products` array. Putting it in the `products` array will prevent Database Auth from activating. Approximately one-third of all Items verified via Database Auth are compatible with Signal Transaction Scores. * No other products besides Signal Transaction Scores and Identity Match are compatible with Database Auth Items. To enable other products for Items where Database Auth is not used, put those products in the `additional_consented_products` array. * `country_codes` should be set to `['US']` – Database Auth is currently only available in the United States. 2. In the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , ensure "Manage via Dashboard" is selected, and enable "Verify with Database Verification". 3. Configure the rules: * (Recommended for most customers) To use Plaid's rules-based, customizable, no-code evaluation logic, select "For certain Database Auth results, fallback". * To use your own evaluation logic, select "For any Database Auth result, complete Link". This option is designed for customers who require more fine-grained control of the Link flow beyond what the ruleset configuration allows, or who have highly sophisticated fraud evaluation systems and require more custom logic. See [Using your own evaluation logic](https://plaid.com/docs/auth/coverage/database-auth/index.html.md#using-your-own-evaluation-logic-advanced) . 4. [Open Link](https://plaid.com/docs/link/index.html.md) according to the instructions for your platform, using the `link_token` created earlier. 5. After the end user completes the Link session, if the session was successful, or if you are using manual evaluation logic, Link will return a `public_token` that you can exchange for an `access_token`. You can then proceed to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) and/or [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) , as described in the main [Auth integration process](https://plaid.com/docs/auth/index.html.md#auth-integration-process) . 6. If the session was unsuccessful, Link will fall back to either an error screen or to a micro-deposit flow, depending on which options you selected in the Account Verification pane. #### Backend-only implementation steps  The backend-only [/auth/verify](https://plaid.com/docs/api/products/auth/index.html.md#authverify) \-based verification process for Database Auth is in early availability. To request access, contact sales or your Plaid account manager. Database Auth can be used to verify account numbers you have already collected without the Plaid Link flow. Call [/auth/verify](https://plaid.com/docs/api/products/auth/index.html.md#authverify) and provide the account and routing number and, optionally, the account owner name. The response will include the same Database Auth-related results as [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) : the verification status, name match score (if a name was provided in the request and name matching data is available), and verification insights. For more details, see the [/auth/verify](https://plaid.com/docs/api/products/auth/index.html.md#authverify) API reference. #### Understanding verification status and name match score  Your business logic will be based on the results of the verification status and the name match score. ##### Verification status  The possible values and most common causes for [verification\_status](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-status) for an Item going through Database Auth are: `database_insights_pass`: Plaid was able to match the account and routing number provided to an existing Item on the Plaid network and has high confidence that the account exists. The account is not known to be closed or frozen. `database_insights_pass_with_caution`: Plaid was unable to match the account and routing number provided to an existing Item on the Plaid network, but the routing number is valid and the account number matches Plaid's known rules for account number formatting at the associated financial institution. `database_insights_fail`: The routing number is not recognized, or the account number does not appear to match the formatting rules at the associated financial institution, or Plaid has received data indicating the account is closed or frozen. In addition to the common causes above, additional risk factors may impact `verification_status` results. Balance is not compatible with Items verified via Database Auth. If you need to check for potential ACH return risk for items verified via Database Auth, you must use Signal Transaction Scores. ###### Understanding the pass with caution verification status  Because `database_insights_pass_with_caution` is a common Database Insights result, how you choose to handle it is important. In a typical test scenario, accepting only `pass` results reduced administrative return rates by over 80%, while accepting both `pass` and `pass_with_caution` reduced administrative return rates by approximately 50%. Note that results will vary based on your own user base and use case and are not guarantees. If you do not want to accept `database_insights_pass_with_caution`, you can configure Link to use a [Fallback method](https://plaid.com/docs/auth/coverage/database-auth/index.html.md#fallback-methods) . Signal Transaction Scores and Identity Match are only compatible with Database Auth Items whose verification status is `database_insights_pass`. If you need to use Signal Transaction Scores to check for non-administrative ACH return risk (e.g. R01 "insufficient funds" returns), or need to check for account takeover fraud using Identity Match, you should not accept the `database_insights_pass_with_caution` status. ##### Name match score  The possible values for the name match score range from 0-100. In general, you should require a name match of at least 70 to effectively protect against account takeover attacks. A name match score will only be returned if the session configuration was enabled for name matching and a name could be found to match against. ###### Example of how to interpret name match score  | Range | Meaning | Example | | --- | --- | --- | | 100 | Exact match | Andrew Smith, Andrew Smith | | 85-99 | Strong match, likely spelling error, nickname, or a missing middle name, prefix or suffix | Andrew Smith, Andrew Simth | | 70-84 | Possible match, likely alias or nickname and spelling error | Andrew Smith, Andy Simth | | 50-69 | Unlikely match, likely relative | Andrew Smith, Betty Smith | | 0-49 | Unlikely match | Andrew Smith, Ray Charles | ##### Using your own evaluation logic (advanced)  If you selected "For any Database Auth result, complete Link", you must write your own code for handling the results of the Database Auth verification. To get the results, call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) and examine the `verification_status`, `verification_insights`, and `verification_name` fields. Based on the values in these fields, you will make a decision on whether to accept the account data as verified, take additional risk mitigation steps, or reject the account data as unverified. The `verification_insights` object will contain more detailed analysis showing exactly which checks passed or failed to result in the given `verification_status`. It will also contain the `name_score`. For more details on the `verification_insights` values, see the [API Reference](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-accounts-verification-insights) . When using your own evaluation logic, you can fallback only to Automated Micro-deposits, and not to Instant Micro-deposits or Same-Day Micro-deposits. When using other verification methods, customers using a [processor partner](https://plaid.com/docs/auth/partnerships/index.html.md) do not typically need to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , and can directly call [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) instead. However, if you are using Database Auth with a processor partner and using your own evaluation logic, you must call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) and check the value of the `verification_status` and/or `verification_insights` fields before passing a processor token to the partner. ##### Fallback methods  If Database Auth fails, you can configure fallback to [Instant Micro-deposits](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-micro-deposits) , [Same-Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) , or [Automated Micro-deposits](https://plaid.com/docs/auth/coverage/automated/index.html.md) via the Account Verification Dashboard. #### Testing Database Auth in Sandbox  For test credentials that can be used to test Database Insights in the Sandbox environment, see [Testing Database Auth](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-database-auth-or-database-insights) . --- # Auth - Database Insights and Match (legacy) | Plaid Docs Database Insights and Match (legacy)  ===================================== #### Evaluate a manually entered account using Plaid network data   (An image of "Payment method selection page showing bank options with search. Car details, insurance info, and payment summary are displayed.") The Database Insights end-user flow with Embedded Institution Search enabled. #### Overview  Database Insights and Database Match have been replaced with Database Auth. The documentation provided here is for the use of customers maintaining support of existing legacy Database Insights integrations. Database Insights (legacy) can increase conversion by providing instant account verification without requiring users to link a bank account via credentials. End users choosing the manual Database Insights path will not be required to log in to their financial institution and instead can enter their account and routing number manually. Database Insights verifies account and routing numbers by checking the information provided against Plaid's known account numbers, leveraging Plaid's database of over 200 million verified accounts. If no match is found, Plaid will check the account number format against known usages by the institution associated with the given routing number. Database Insights will provide a verification status of 'pass', 'pass with caution', or 'fail' and a set of attributes that contributed to that status, such as whether a match was found or whether Plaid fell back to checking account number formats. Database Insights does not verify that the user has access to the bank account and Database Insights does also not fully guarantee that the account exists, especially in a 'pass with caution' scenario. For these reasons, Database Insights should only be enabled where there is a low risk of fraud or ACH returns. Examples of use cases where Database Insights may be appropriate include bill payment, rent collection, business to business payments, or subscription payments. Approximately 30% of Items verified by Database Insights can also be verified by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) or [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) . For more details, see [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) and [Signal Transaction Scores](https://plaid.com/docs/signal/index.html.md) . All Items verified with Database Insights are also compatible with account ownership identity verification via [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) . Database Insights and [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) are both designed to increase adoption of ACH payment methods and are frequently used together. Database Insights is also fully compatible with the standard, non-Embedded Institution Search Link flow. ##### Database Insights flow  1. Starting on a page in your app, the user clicks an action that opens Plaid Link. 2. Inside of Plaid Link, the user selects an option to enter the manual verification flow and provides their account and routing number. 3. Once the user has submitted their information, Link closes and returns a `public_token` within the `onSuccess` callback. 4. Call `/item/token/exchange` to exchange the `public_token` for an `access_token`, then call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) to obtain the account numbers and the verification results. 5. Based on the values of the `verification_status` and `verification_insights` fields returned by [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , make a decision whether to proceed with the account information for ACH or to reject the account information as unverified. When using other flows, customers using a [processor partner](https://plaid.com/docs/auth/partnerships/index.html.md) do not typically need to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , and can directly call [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) instead. However, if you are using Database Insights with a processor partner, you must call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) and check the value of the `verification_status` and/or `verification_insights` fields before passing a processor token to the partner. #### Implementation steps  ##### Create a link\_token  Create a `link_token` with the following parameters: * The `products` array should include only `auth` or `transfer` as a product when using Database Insights. While in most cases additional products can be added to existing Plaid Items, Items created with Database Insights are an exception and cannot be used with any Plaid products other than Auth, Transfer, Signal, or Identity Match. Approximately 30% of Items verified by Database Insights can also be verified by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) or Signal. For more details, see [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) and [Signal](https://plaid.com/docs/signal/signal-rules/index.html.md#data-availability-limitations) . If using Identity Match or Signal in this way, they should be added to the Item via the `required_if_supported_products`, `optional_products`, or `additional_consented_products` fields rather than the `products` array. * `country_codes` should be set to `['US']` or `['CA']`– Database Insights is currently only available in the United States or Canada. * The `auth` object should specify `"database_insights_enabled": true`. * (Optional) Within the `auth` object, specify `"auth_type_select_enabled": true` in order to enable [Auth Type Select](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#adding-manual-verification-entry-points-with-auth-type-select) , which will surface the manual entry point for Database Insights on the default Link screen. If Auth Type Select is not enabled, credential-based flows will be the primary UI flow and the Database Insights entry point will only appear as a fallback, except when using [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) . Database Insights cannot be used in the same session as Database Match, Same-Day Micro-deposits, or Instant Micro-deposits. If any of those flows are explicitly enabled in the `auth` object alongside Database Insights, an error will occur when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . If they are implicitly enabled due to account default settings, they will be overridden by enabling Database Insights. ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user": {"client_user_id": "${UNIQUE_USER_ID}"}, "client_name": "Plaid App", "products": ["auth"], "country_codes": ["US"], "language": "en", "webhook": "https://sample-web-hook.com", "redirect_uri": "https://domainname.com/oauth-page.html", "auth": { "database_insights_enabled": true } }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: "user-id", }, client_name: 'Plaid Test App', products: ['auth'], country_codes: ['US'], language: "en", webhook: 'https://webhook.sample.com', link_customization_name: "default", auth: { database_insights_enabled: true }, } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```node const request: LinkTokenCreateRequest = { user: { client_user_id: new Date().getTime().toString() }, client_name: 'Plaid App', products: [Products.Auth], country_codes: [CountryCode.Us], webhook: 'https://webhook.sample.com', language: 'en', auth: { database_insights_enabled: true }, }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```java LinkTokenCreateRequestAuth auth = new LinkTokenCreateRequestAuth() .databaseInsightsEnabled(true); LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Test app") .products(Arrays.asList(Products.AUTH)) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .webhook("https://example.com/webhook") .linkCustomizationName("default") .accountFilters(accountFilters) .auth(auth); ``` ```python request = LinkTokenCreateRequest( products=[Products('auth')], client_name="Plaid Test App", country_codes=[CountryCode('US')], language='en', webhook='https://sample-webhook-uri.com', link_customization_name='default', user=LinkTokenCreateRequestUser( client_user_id='user-id', ), auth=LinkTokenCreateRequestAuth( database_insights_enabled=True, ) ) response = client.link_token_create(request) ``` ```go user := plaid.LinkTokenCreateRequestUser{ ClientUserId: "user-id", } request := plaid.NewLinkTokenCreateRequest( "Plaid Test", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetProducts([]plaid.Products{plaid.PRODUCTS_AUTH}) request.SetLinkCustomizationName("default") request.SetWebhook("https://webhook-uri.com") var databaseInsightsEnabled bool = true request.SetAuth(plaid.LinkTokenCreateRequestAuth{ DatabaseInsightsEnabled: &databaseInsightsEnabled, }) resp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := resp.GetLinkToken() ``` ##### Initialize Link with a link\_token  After creating a `link_token` for the `auth` product, use it to initialize Plaid Link. When the user successfully inputs their account and routing numbers, the `onSuccess()` callback function will return a `public_token`. App.js ```javascript const linkHandler = Plaid.create({ // Fetch a link_token configured for 'auth' from your app server token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token and connected accounts to your app server $.post('/exchange_public_token', { publicToken: public_token, accounts: metadata.accounts, }); metadata = { ..., link_session_id: String, institution: { name: null, // name is always null for Database Insights institution_id: null // institution_id is always null for Database Insights }, accounts: [{ id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D', mask: '1234', name: null, type: 'depository', subtype: 'checking', verification_status: '' }] } }, // ... }); // Open Link on user-action linkHandler.open(); ``` ##### Exchange the public token  In your own backend server, call the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint with the Link `public_token` received in the `onSuccess` callback to obtain an `access_token`. Persist the returned `access_token` and `item_id` in your database in relation to the user. ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" }' ``` ```node // publicToken and accountID are sent from your app to your backend-server const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D'; const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d'; // Obtain an access_token from the Link public_token try { const response = await client.itemPublicTokenExchange({ public_token: publicToken, }); const accessToken = response.data.access_token; } catch (err) { // handle error } ``` ```python # publicToken and accountID are sent from your app to your backend-server accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D' publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' # Obtain an access_token from the Link public_token token_request = ItemPublicTokenExchangeRequest( public_token=publicToken) token_response = client.item_public_token_exchange(token_request) accessToken = token_response['access_token'] ``` ```ruby # publicToken and accountID are sent from your app to your backend-server accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D' publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' # Obtain an access_token from the Link public_token request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: publicToken } ) token_response = client.item_public_token_exchange(request) access_token = token_response.access_token ``` ```java // publicToken and accountID are sent from your app to your backend-servers String accountID = "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"; String publicToken = "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"; // Obtain an access_token from the Link public_token ItemPublicTokenExchangeRequest tokenRequest = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response tokenResponse = plaidClient .itemPublicTokenExchange(tokenRequest) .execute(); String accessToken = tokenResponse.body().getAccessToken(); ``` ```go // publicToken and accountID are sent from your app to your backend-server accountID := "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D" publicToken := "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" // Obtain an access_token from the Link public_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest(publicToken), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() ``` Exchange token response ```json { "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755", "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op", "request_id": "m8MDnv9okwxFNBV" } ``` ##### Fetch Auth data and verification results  Next, we can retrieve Auth data, along with the results of the Database Insights verification check, by calling [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) . ```bash curl -X POST https://sandbox.plaid.com/auth/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755" }' ``` ```node const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755'; // Instantly fetch Auth numbers const request: AuthGetRequest = { access_token: accessToken, }; try { const response = await client.authGet(request); const numbers = response.data.numbers; } catch (err) { // handle error } ``` ```python access_token = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755' # Instantly fetch Auth numbers auth_request = AuthGetRequest(access_token=access_token) auth_response = client.auth_get(auth_request) numbers = auth_response['numbers'] ``` ```ruby access_token = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755'; # Instantly fetch Auth numbers auth_get_request = Plaid::AuthGetRequest.new auth_get_request.access_token = access_token auth_response = client.auth_get(auth_get_request) numbers = auth_response.numbers ``` ```java String accessToken = "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755"; // Instantly fetch Auth numbers AuthGetRequest authGetRequest = new AuthGetRequest() .accessToken(accessToken); Response authResponse = client() .authGet(authGetRequest) .execute(); if (authResponse.isSuccessful()) { AuthGetResponse.Numbers numbers = authResponse.body().getNumbers(); } ``` ```go accessToken := "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755" // Instantly fetch Auth numbers authGetResp, _, err := client.PlaidApi.AuthGet(ctx).AuthGetRequest( *plaid.NewAuthGetRequest(accessToken), ).Execute() numbers := authGetResp.GetNumbers() ``` Auth response ```json { "numbers": { "ach": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "account": "9900009606", "routing": "011401533", "wire_routing": "021000021" } ], "eft": [], "international": [], "bacs": [] }, "accounts": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "balances": { Object }, "mask": "0000", "name": null, "official_name": null, "verification_status": "database_insights_pass", "verification_insights": { "network_status": { "has_numbers_match": true, "is_numbers_match_verified": true }, "previous_returns": { "previous_administrative_return": false }, "account_number_format": "valid" }, "subtype": "checking", "type": "depository" } ], "item": { Object }, "request_id": "m8MDnv9okwxFNBV" } ``` #### Making a risk determination  The results of the Database Insights verification can be found in the `verification_status` and `verification_insights` fields returned by [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) . Based on the values in these fields, you will make a business decision on whether to accept the account numbers as verified, take additional risk mitigation steps, or reject the account numbers as unverified. #### Testing Database Insights in Sandbox  For test credentials that can be used to test Database Insights in the Sandbox environment, see [Testing Database Auth or Database Insights](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-database-auth-or-database-insights) . #### Database Match  Database Insights and Database Match have been replaced with Database Auth. The documentation provided here is for the use of customers maintaining existing legacy Database Insights and Database Match integrations. [Database Match](https://plaid.com/docs/auth/coverage/database/index.html.md#database-match) enables instant manual account verification without the need for micro-deposits, instead relying on Plaid's database of known account numbers. When provided as an alternative to Same-Day Micro-deposits, Database Match can increase conversion, as the user may be able to verify instantly, without having to return to Plaid to verify their micro-deposit codes. Database Match will present the user with the option to manually add a bank account in Link by providing their name, account number, and routing number. Plaid will then check this information against its network of over 200 million known bank accounts. Approximately 30% of user bank accounts can be verified via Database Match. If a match is not found, Database Match will fall back to routing the user to a manual micro-deposit flow, either Instant Micro-deposits or Same-Day Micro-deposits. Database Match can be used to verify the validity of the bank account being linked, but it does not verify that the end user has access to the bank account. To mitigate account takeover risk with Database Match, it can be paired with [Identity Match](https://plaid.com/docs/identity/index.html.md) to verify the user's information, such as phone number and address, on the linked account. ##### Database Match flow  1. Starting on a page in your app, the user clicks an action that opens Plaid Link. 2. Inside of Plaid Link, the user selects an option to enter the manual verification flow and provides their legal name, account and routing number. 3. Plaid will confirm the account number, routing number, and name match a previously verified account. 4. If a match is confirmed, Link closes with a `public_token` and a verification status of `database_matched`. 5. If there is no match, the user will be prompted to enter the Instant or Same Day Micro-deposits flow. When these steps are complete, you can call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to obtain an `access_token` for calling endpoints such as [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) . ##### Database Match implementation steps  To enable Database Match, use the same settings as Same-Day Micro-deposits. You can then enable the feature in one of two ways: * When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , set `auth.database_match_enabled: true`. * [In the Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , enable Database Match. Database Match cannot be used in the same session as [Database Insights](https://plaid.com/docs/auth/coverage/database/index.html.md) . If Database Insights is explicitly enabled in the `auth` object alongside Database Match, an error will occur when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user": {"client_user_id": "${UNIQUE_USER_ID}"}, "client_name": "Plaid App", "products": ["auth"], "country_codes": ["US"], "language": "en", "webhook": "https://sample-web-hook.com", "redirect_uri": "https://domainname.com/oauth-page.html", "auth": { "database_match_enabled": true, "same_day_microdeposits_enabled": true, } }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: "user-id", }, client_name: 'Plaid Test App', products: ['auth'], country_codes: ['US'], language: "en", webhook: 'https://webhook.sample.com', link_customization_name: "default", auth: { database_match_enabled: true, same_day_microdeposits_enabled: true }, } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```node const request: LinkTokenCreateRequest = { user: { client_user_id: new Date().getTime().toString() }, client_name: 'Plaid App', products: [Products.Auth], country_codes: [CountryCode.Us], webhook: 'https://webhook.sample.com', language: 'en', auth: { database_match_enabled: true, same_day_microdeposits_enabled: true }, }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```java LinkTokenCreateRequestAuth auth = new LinkTokenCreateRequestAuth() .databaseMatchEnabled(true); LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("WonderWallet") .products(Arrays.asList(Products.AUTH)) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .webhook("https://example.com/webhook") .linkCustomizationName("default") .accountFilters(accountFilters) .auth(auth); ``` ```python request = LinkTokenCreateRequest( products=[Products('auth')], client_name="Plaid Test App", country_codes=[CountryCode('US')], language='en', webhook='https://sample-webhook-uri.com', link_customization_name='default', user=LinkTokenCreateRequestUser( client_user_id='user-id', ), auth=LinkTokenCreateRequestAuth( database_match_enabled=True, same_day_microdeposits_enabled=True, ) ) response = client.link_token_create(request) ``` ```go user := plaid.LinkTokenCreateRequestUser{ ClientUserId: "user-id", } request := plaid.NewLinkTokenCreateRequest( "Plaid Test", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetProducts([]plaid.Products{plaid.PRODUCTS_AUTH}) request.SetLinkCustomizationName("default") request.SetWebhook("https://webhook-uri.com") var databaseMatchEnabled bool = true var sameDayMicrodepositsEnabled bool = true request.SetAuth(plaid.LinkTokenCreateRequestAuth{ DatabaseMatchEnabled: &databaseMatchEnabled, SameDayMicrodepositsEnabled: &sameDayMicrodepositsEnabled, }) resp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := resp.GetLinkToken() ``` When calling [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , the returned object will have a `verification_status` value of `database_matched` as an indication that the user's data was verified through Database Match. Auth response for Database Match ```json { "numbers": { "ach": [ { "account": "1111222233330000", "routing": "011401533", "wire_routing": "021000021" } ], ... }, "accounts": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "balances": { Object }, "mask": "0000", "name": "Checking...0000", "official_name": null, "verification_status": "database_matched", "subtype": "checking", "type": "depository" } ], ... } ``` ##### Testing Database Match in Sandbox  For test credentials that can be used to test Database Match in the Sandbox environment, see [Testing Database Match](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-database-match) . --- # Auth - Configuring entry points | Plaid Docs Configuring Auth entry points  ============================== #### Configure end users' options for verifying their account with Reroute to Credentials and Auth Type Select  #### Default manual verification flow entry point  When using the default flow, the **Link with account numbers** entry point will appear when the user does any of the following: * Encounters an error in the Link flow * Selects an institution whose connection health is poor * Attempts to close the Link modal without connecting an institution * Receives a "no results" message when searching for an institution * Scrolls to the bottom of the institution search results To trigger this flow via the [Link demo](https://plaid.com/link-demo) specify **Auth** in the Product dropdown menu and then **Launch Demo**. Trigger empty search results (type in a search query like 'xyz') or the Exit Pane (by closing Link) and select **Link with account numbers**. This entry point will direct the user to Database Auth, Instant Micro-deposits, or Same-Day Micro-deposits, depending on which fallback options you have enabled and on whether the institution supports Instant ACH. You can change these entry points using the features Auth Type Select and Reroute to Credentials. Auth Type Select adds a prompt for the end user to pick a manual Auth flow upfront, without hitting any of the triggers above. Reroute to Credentials is the opposite: it guides or forces the end user away from manual Auth flows if Plaid detects that the end user's institution is supported with a non-manual flow. #### Adding manual verification entry points with Auth Type Select  (An image of "Plaid auth manual link flow, select bank link option: Instantly or Manually. Continue button visible at the bottom.") Auth Type Select is a Link configuration that shows a pane upfront, enabling end users to actively choose between credential-based authentication and manual account authentication at the start of the Plaid Link flow. To demo **Auth Type Select** via the [Plaid Link demo](https://plaid.com/demo) , specify **United States** and **Auth** in the Country and Product dropdown menu respectively. Toggle on Auth Type Select, then **Launch Demo**. To enable Auth Type Select, use the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , or, if not using the Dashboard Account Verification pane, set `auth.auth_type_select_enabled: true` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . (An image of "Embedded institution search with Auth Type Select enabled, showing bank options and payment plan selection for PetGuard insurance.") Embedded Institution Search with Auth Type Select enabled ##### When to use Auth Type Select  Auth Type Select is best for customers who expect that a substantial portion of their consumers would prefer to authenticate manually, and who prefer to maximize Auth coverage over other data products. Examples may include business account verification use cases where a high percentage of users are not expected to have access to credentials of a bank account. Customers that see the greatest success with the Auth Type Select configuration have a substantial portion of users (over half, as a rule of thumb) who cannot or will not connect by logging into their bank, who have invested in fraud risk mitigations or have a low risk use case, and/or have very high intent users (such as users connecting a bank account to receive a payment). Some customers observe an increase in conversion of verified Auth data with this configuration. However, this configuration reduces coverage of other products. When offered the manual option upfront, more users may choose to link manually. Users who opt to connect via micro-deposits can have lower conversion than Instant Auth because the flow requires more steps for a user, including potentially returning to Link the next day to verify micro-deposits. It may encourage users to connect via micro-deposits who would otherwise connect via credential-based Auth types (if the manual option was not available upfront). This configuration is best for customers who want to maximize Auth coverage and can tolerate reduced coverage of other products like Balance and Identity. #### Removing manual verification entry points with Reroute to Credentials  Reroute to Credentials will prompt users to use a login-based verification flow if they attempt to use a manual verification flow with an institution where login-based flows are supported. [Optional Reroute to Credentials](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#optional-reroute) (the default Link flow) provides a nudge to use a login-based flow, but will not block manual verification, whereas [Forced Reroute to Credentials](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#forced-reroute) will block manual verification if login-based flows are available. Alternatively, you can [disable Reroute to Credentials](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#no-reroute) entirely. (An image of "no description available") Forced Reroute to Credentials example flow In some cases, when rerouting a user to a supported institution, Plaid may show a list of institutions instead of a single institution. This can occur when a financial institution has multiple different brands that share a common routing number. ##### Optional Reroute  Optional Reroute to Credentials is the default flow. It is best for customers who would like to make a recommendation for the user to connect via credentials, but not block the user from proceeding with the Same Day Micro-deposits flow. This flow will provide a reminder to the user that the institution is supported, and detail the benefits of instant connection, while also leaving the manual verification option in place. To enable Optional Reroute, you do not need to take any action. If you have disabled Optional Reroute (by enabling [Forced Reroute](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#forced-reroute) or [No Reroute](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#no-reroute) ), you can re-enable it by using the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , or set `auth.reroute_to_credentials: "OPTIONAL"` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. | Single Institution Optional Reroute | Multiple Institution Optional Reroute | | --- | --- | | (An image of "Sign in to Gingham Bank via Plaid using routing number 12341234. Tap 'Continue' or 'Enter account number instead.'") | (An image of "Mobile screen with options to select a financial institution. Choices: Gingham Bank, Herringbone Treasury. Option to enter account number.") | ##### Forced Reroute  Forced Reroute to Credentials is best for customers who would like to restrict the user to connect via credentials if the institution is supported on a credential-based flow and stop the user from proceeding with a manual flow. This flow is designed to block a user from connecting manually for institutions that are supported via credentials in high ACH risk use cases. To enable Forced Reroute, use the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , or set `auth.reroute_to_credentials: "FORCED"` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. | Single Institution Forced Reroute | Multiple Institution Forced Reroute | | --- | --- | | (An image of "Sign in to Gingham Bank using Wonderwallet with routing number 12341234. Press 'Continue' to securely connect your account.") | (An image of "Select an institution based on routing number 12345678. Options: Gingham Bank, Herringbone Treasury. Sign in required.") | ##### No Reroute  To completely disable Reroute to Credentials, use the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) , or set `auth.reroute_to_credentials: "OFF"` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. --- # Auth - Additional Auth flows | Plaid Docs Additional verification methods  ================================ #### Support Auth for more US financial institutions and users  #### Overview  Instant Auth covers approximately 95% of users' eligible bank accounts. For the remaining ~5%, or users who choose not to use instant credential verification, Plaid offers users the ability to verify their accounts through an optimized set of database verification and micro-deposit verification methods. [Our video tutorial also provides a comprehensive guide to adding Auth using micro-deposits](https://www.youtube.com/watch?v=FlZ5nzlIq74) The following Auth methods are enabled in your app by default once you have integrated Auth: * [Instant Auth](https://plaid.com/docs/auth/coverage/instant/index.html.md) : User enters their credentials and is authenticated immediately. This is the default flow. * [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) (US only): User enters their credentials, account number, and routing number. Plaid matches user input against masked values and authenticates immediately. To increase conversion, you can enable the following additional Auth methods: * [Automated Micro-deposits](https://plaid.com/docs/auth/coverage/automated/index.html.md) (US only): User enters their credentials, account number, and routing number. Plaid makes a micro-deposit and automatically verifies the deposit in as little as one to two business days. * [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) (US only): User enters account and routing numbers. Plaid attempts to match this data against known-good account and routing numbers recognized on the Plaid network. * [Instant Micro-deposits](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-micro-deposits) (US only): User enters account and routing numbers. Plaid makes a RTP or FedNow micro-deposit and the user manually verifies the code in as little as 5 seconds. * [Same Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) (US only): User enters account and routing numbers. Plaid makes a Same Day ACH micro-deposit and the user manually verifies the code in as little as one business day. To see each of these flows in action, check out the [Auth workflows demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100) . ##### Auth method comparison chart  | Method | Best for | Verification timeframe | Requires additional integration work | Countries supported | | --- | --- | --- | --- | --- | | [Instant Auth](https://plaid.com/docs/auth/coverage/instant/index.html.md) | All risk profiles | Instant | No (enabled by default) | US, CA | | [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) | All risk profiles | Instant | No (enabled by default) | US | | [Automated Micro-deposits](https://plaid.com/docs/auth/coverage/automated/index.html.md) | All risk profiles | 1-2 business days | No, but requires "pending verification" UX state in app | US | | [Instant Micro-deposits](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-micro-deposits) | Low and medium risk profiles | Instant | No | US | | [Same Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) | Low and medium risk profiles | 1-2 business days, plus wait for user interaction | Yes, and requires "pending verification" UX state in app | US | | [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) | Low and medium risk profiles | Instant | No, unless used in advanced configuration mode | US, CA (CA in early availability) | | | | | | | Accounts verified via Database Auth, Instant Micro-deposits, or Same-Day Micro-deposits do not have active data connections with a financial institution. These accounts and their associated Items can only be used with Auth and Transfer, not with any other Plaid products (such as Balance or Transactions), with the partial exception of [Identity Match](https://plaid.com/docs/identity/index.html.md#using-identity-match-with-micro-deposit-or-database-items) and [Signal Transaction Scores](https://plaid.com/docs/signal/signal-rules/index.html.md#data-availability-limitations) . Because of this limitation, accounts verified via these methods may be more vulnerable to fraud or return risk. Consider your level of risk exposure and current anti-fraud measures before enabling these methods. For more details, see [Anti-fraud best practices](https://plaid.com/docs/auth/coverage/same-day-link-best-practices/index.html.md) . #### Entry points  To learn more about when Plaid presents Database Auth, Instant Micro-deposits, or Same-Day Micro-deposits as options, and to customize the Link user experience around these flows, see [Configuring entry points](https://plaid.com/docs/auth/coverage/flow-options/index.html.md) . #### Integration instructions  Most additional Auth methods can be enabled in the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) with no additional integration work, as long as the following requirements are met: * The `country_codes` array in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) is set to `["US"]`. Additional Auth methods are not available if other countries are selected (with an exception for Database Auth, if you have contacted your account manager for Canada access). * The `products` array does not contain any products other than `auth` or `transfer`. Any other products you want to use must be configured in the `additional_consented_products`, `required_if_supported_products`, or `optional_products` arrays and will be used on a best-effort basis. [Same-Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) requires additional integration work, as you will need to present a Link UI where the end user can verify the micro-deposit description. For more details, see [Same-Day micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) . [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) , if used in the advanced mode where fallback rules are not configured in the Dashboard, requires additional integration work. For more details, see [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) . (An image of "Alt text: 'Account Verification Dashboard with settings for instant verification methods, additional methods toggle, and micro-deposit options.'") Example of some configuration options available in the Account Verification Dashboard #### Institution coverage  To see which Auth methods a given institution supports, you can call [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) with [options.include\_auth\_metadata](https://plaid.com/docs/api/institutions/index.html.md#institutions-get-request-options-include-auth-metadata) set to `true`. The results will be returned in the [auth\_metadata.supported\_methods object](https://plaid.com/docs/api/institutions/index.html.md#institutions-get-response-institutions-auth-metadata-supported-methods) in the response. Alternatively, you can see this information on the [Institution Status page](https://dashboard.plaid.com/activity/status) in the Plaid Dashboard. The Same Day Micro-deposits and Database Auth methods will not appear in these results, as they do not depend on institution capabilities and are available at all institutions. --- # Auth - Instant Auth, Instant Match, & Instant Micro-deposits | Plaid Docs Instant Auth, Instant Match, and Instant Micro-Deposits  ======================================================== #### Learn how to authenticate your users instantly  #### Instant Auth  Instant Auth supports more than 6,200 financial institutions with credential-based login. Instant Auth is the default Auth method and does not require extra configuration steps if Auth is already configured in your app. For clarity and completeness, the section below explains how to configure Instant Auth. The user launches Link... (An image of "The user launches Link...") (An image of "...and selects the institution to link.") (An image of "They are handed off to the institution...") (An image of "...and log in.") (An image of "Next, they select the account to link. (Single-account select is typically recommended for Auth.)") (An image of "...and their account is linked!") You can try out the Instant Auth flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=4) . ##### Configure & Create a link\_token  Create a `link_token` with the following parameters: * `products` array containing `auth` – If you are using only `auth` and no other products, `auth` must be specified in the Products array. Other products (such as `identity`) may be specified as well. If you are using multiple products, `auth` is not required to be specified in the products array, but including it is recommended for the best user experience. ```node app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['auth'], language: 'en', webhook: 'https://webhook.example.com', redirect_uri: 'https://domainname.com/oauth-page.html', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "products": ["auth"], "country_codes": ["US"], "language": "en", "webhook": "https://webhook.example.com", "redirect_uri": "https://domainname.com/oauth-page.html" }' ``` ```ruby post '/api/create_link_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: client_user_id }, client_name: 'Plaid Test App', products: ['auth'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.example.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.Products; import com.plaid.client.model.CountryCode; import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; public class PlaidExample { ... static class GetLinkToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.fromValue("auth"))) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .redirectUri("https://domainname.com/oauth-page.html") .webhook("https://webhook.example.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.link_token_create_request import LinkTokenCreateRequest from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser from plaid.model.products import Products from plaid.model.country_code import CountryCode @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( products=[Products("auth")], client_name="Plaid Test App", country_codes=[CountryCode('US')], redirect_uri='https://domainname.com/oauth-page.html', language='en', webhook='https://webhook.example.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetRedirectUri("https://domainname.com/oauth-page.html") request.SetProducts([]plaid.Products{plaid.PRODUCTS_AUTH}) resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` ##### Initialize Link with a link\_token  After creating a `link_token` for the `auth` product, use it to initialize Plaid Link. When the user inputs their username and password for the financial institution, the `onSuccess()` callback function will return a `public_token`. App.js ```javascript Plaid.create({ // Fetch a link_token configured for 'auth' from your app server token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token and accounts to your app server $.post('/exchange_public_token', { publicToken: public_token, accounts: metadata.accounts, }); }, }); ``` ##### Exchange the public\_token and fetch Auth data  In your own backend server, call the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint with the Link `public_token` received in the `onSuccess` callback to obtain an `access_token`. Persist the returned `access_token` and `item_id` in your database in relation to the user. You will use the `access_token` when making requests to the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) endpoint. ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" }' curl -X POST https://sandbox.plaid.com/auth/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}" }' ``` ```node const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d'; try { // Obtain an access_token from the Link public_token const tokenResponse = await client.itemPublicTokenExchange({ public_token: publicToken}); const accessToken = tokenResponse.access_token; // Instantly fetch Auth numbers const request: AuthGetRequest = { access_token: accessToken, }; const response = await plaidClient.authGet(request); const numbers = response.data.numbers; } catch (err) { // handle error } ``` ```python publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' # Obtain an access_token from the Link public_token token_request = ItemPublicTokenExchangeRequest( public_token=publicToken) token_response = client.item_public_token_exchange(token_request) accessToken = token_response['access_token'] # Instantly fetch Auth numbers auth_request = AuthGetRequest(access_token=accessToken) auth_response = client.auth_get(auth_request) numbers = auth_response['numbers'] ``` ```ruby publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d'; # Obtain an access_token from the Link public_token item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: publicToken } ) token_response = client.item_public_token_exchange( item_public_token_exchange_request ) accessToken = token_response.access_token # Instantly fetch Auth numbers auth_get_request = Plaid::AuthGetRequest.new auth_get_request.access_token = accessToken auth_response = client.auth_get(auth_get_request) numbers = auth_response.numbers ``` ```java String publicToken = "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"; // Obtain an access_token from the Link public_token ItemPublicTokenExchangeRequest tokenRequest = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response tokenResponse = plaidClient .itemPublicTokenExchange(tokenRequest) .execute(); if (tokenResponse.isSuccessful()) { String accessToken = tokenResponse.body().getAccessToken(); // Instantly fetch Auth numbers AuthGetRequest authGetRequest = new AuthGetRequest() .accessToken(accessToken); Response authResponse = client() .authGet(authGetRequest) .execute(); if (authResponse.isSuccessful()) { AuthGetResponse.Numbers numbers = authResponse.body().getNumbers(); } } ``` ```go publicToken := "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" // obtain an access_token from the Link public_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest(publicToken), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() // Instantly fetch Auth numbers authGetResp, _, err := client.PlaidApi.AuthGet(ctx).AuthGetRequest( *plaid.NewAuthGetRequest(accessToken), ).Execute() ``` Check out the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) API reference documentation to see the full Auth request and response schema. Auth response ```json { "numbers": { "ach": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "account": "9900009606", "routing": "011401533", "wire_routing": "021000021" } ], "eft": [], "international": [], "bacs": [] }, "accounts": [{ Object }], "item": { Object }, "request_id": "m8MDnv9okwxFNBV" } ``` #### Instant Match  Instant Match is available for approximately 800 U.S. additional financial institutions where Instant Auth is not available. Instant Match is enabled automatically for Auth customers and is automatically provided at supported institutions as a fallback experience when Instant Auth is not available. When using Instant Match, Plaid Link will prompt your user to enter their account number and routing number for a depository account. Plaid will then verify the last four digits of the user-provided account number against the account mask retrieved from the financial institution. The user launches Link... (An image of "The user launches Link...") (An image of "...and selects the institution to link.") (An image of "They find their institution...") (An image of "...and log in.") (An image of "Next, they select the account to link. (Single-account select is typically recommended for Auth.)") (An image of "They verify their bank's routing and account numbers...") (An image of "If those numbers match the account masks that Plaid has retrieved, the account is verified") You can try out the Instant Match flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=4) . See more details in our [testing guide](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-instant-match) . When using Instant Match, the user can verify only a single account. Even if the Account Select properties allow selecting all or multiple accounts, the ability to select multiple depository accounts for Auth will be disabled in Link if the institution is using the Instant Match flow. ##### Configuring in Link  Instant Match will be enabled automatically if you configure the `link_token` with the following parameters: * add `"auth"` to `products` array * `country_codes` set to `['US']` (adding any other countries to the array will disable Instant Match) Optionally, you can disable Instant Match on a per-session basis via the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call, by setting `"auth.instant_match_enabled": false` in the request body. If you would like to disable Instant Match automatically for all Link sessions, contact your account manager or file a support ticket via the Dashboard. ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user": {"client_user_id": "${UNIQUE_USER_ID}"}, "client_name": "Plaid App", "products": ["auth"], "country_codes": ["US"], "language": "en", "webhook": "https://sample-web-hook.com" }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: "user-id", }, client_name: 'Plaid Test App', products: ['auth'], country_codes: ['US'], language: "en", webhook: 'https://webhook.sample.com', link_customization_name: "default", } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```node const request: LinkTokenCreateRequest = { user: { client_user_id: new Date().getTime().toString() }, client_name: 'Plaid App', products: [Products.Auth], country_codes: [CountryCode.Us], language: 'en', }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("very nice client name") .products(Arrays.asList(Products.AUTH)) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .webhook("https://example.com/webhook") .linkCustomizationName("default") .accountFilters(accountFilters); ``` ```python request = LinkTokenCreateRequest( products=[Products('auth')], client_name="Plaid Test App", country_codes=[CountryCode('US')], language='en', webhook='https://sample-webhook-uri.com', link_customization_name='default', user=LinkTokenCreateRequestUser( client_user_id='user-id', ) ) response = client.link_token_create(request) ``` ```go user := plaid.LinkTokenCreateRequestUser{ ClientUserId: "user-id", } request := plaid.NewLinkTokenCreateRequest( "Plaid Test", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetProducts([]plaid.Products{plaid.PRODUCTS_AUTH}) request.SetLinkCustomizationName("default") request.SetWebhook("https://webhook-uri.com") var instantMatchEnabled bool = true resp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := resp.GetLinkToken() ``` ##### Handling Link events  For a user who goes through the Instant Match flow, the `TRANSITION_VIEW (view_name = NUMBERS)` event will occur after `SUBMIT_CREDENTIALS`, and in the `onSuccess` callback the `verification_status` will be `null` because the user would have been verified instantly. Sample Link events for Instant Match flow ```bash OPEN (view_name = CONSENT) TRANSITION_VIEW (view_name = SELECT_INSTITUTION) SEARCH_INSTITUTION SELECT_INSTITUTION TRANSITION_VIEW (view_name = CREDENTIAL) SUBMIT_CREDENTIALS TRANSITION_VIEW (view_name = LOADING) TRANSITION_VIEW (view_name = MFA, mfa_type = code) SUBMIT_MFA (mfa_type = code) TRANSITION_VIEW (view_name = LOADING) TRANSITION_VIEW (view_name = SELECT_ACCOUNT) TRANSITION_VIEW (view_name = NUMBERS) TRANSITION_VIEW (view_name = LOADING) TRANSITION_VIEW (view_name = CONNECTED) HANDOFF onSuccess (verification_status: null) ``` #### Instant Micro-deposits  Instant Micro-deposits is the Plaid product term for our ability to authenticate any bank account in the US that is supported by RTP or FedNow. For over 80 Plaid-supported banks, Instant Micro-deposits is the fastest and highest-converting form of Auth support available. If both Instant Micro-deposits and Same Day Micro-deposits are enabled, any user who attempts a micro-deposit with one of the over 400 eligible RTP or FedNow routing numbers will automatically experience the Instant Micro-deposits flow and be able to verify instantly. ##### Instant Micro-deposit flow  The user launches Link... (An image of "The user launches Link...") (An image of "...and selects the institution to link.") (An image of "They find their institution...") (An image of "...enter their account info...") (An image of "...their name...") (An image of "...and their account type.") (An image of "The user authorizes Plaid to make a deposit, and the deposit is made immediately.") (An image of "The user is then prompted to enter the code associated with the deposit.") (An image of "If the code matches the one that Plaid generated with the deposit description, the user's account is verified.") 1. Starting on a page in your app, the user clicks an action that opens Plaid Link. 2. Inside of Plaid Link, the user enters the micro-deposit initiation flow and provides their legal name, account and routing number. 3. Plaid sends a micro-deposit to the user's account that will post within 5 seconds, and directs the user to log into their bank account to obtain the code from the micro-deposit description. 4. The user enters the code from the micro-deposit description into Plaid Link. 5. Upon success, Link closes with a `public_token` and a `metadata` account status of `manually_verified`. Plaid will not reverse the $0.01 micro-deposit credit. When these steps are done, your user's Auth data is verified and ready to fetch. You can try out the Instant Micro-deposits flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=7) . ##### Configuring in Link  Instant Micro-deposits will be enabled if you configure the `link_token` with the following parameters: * Set the `products` array to `["auth"]`. While in most cases additional products can be added to existing Plaid Items, Items created for micro-deposit verification cannot be used with any Plaid products other than Auth or Transfer, with the exception that approximately 30% of Items verified by Instant micro-deposits can also be verified by [Identity Match](https://plaid.com/docs/identity/index.html.md#using-identity-match-with-micro-deposit-or-database-items) and evaluated for [Signal Transaction Scores](https://plaid.com/docs/signal/signal-rules/index.html.md#data-availability-limitations) . * `country_codes` set to `['US']` (adding any other countries to the array will disable Instant Micro-deposits) * `auth.instant_microdeposits_enabled` set to `true`. For Plaid teams created prior to November 2023 this setting is not required; for newer teams, it must be manually configured. Optionally, you can disable Instant Match on a per-session basis via the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call, by setting `"auth.instant_microdeposits_enabled": false` in the request body. If you would like to disable Instant Match automatically for all Link sessions, contact your account manager or file a support ticket via the Dashboard. ##### Entering the Instant Micro-deposit flow  Your user will enter the Instant Micro-deposit flow in the following scenarios: * The user selects an eligible institution that is not enabled for Instant Auth, Instant Match, or Automated Micro-deposits. * The Link session has [Same Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) enabled and the user enters an eligible routing number during the Same Day Micro-deposits flow. In this case, the session will be "upgraded" to use Instant Micro-deposits rather than Same-Day Micro-deposits. ###### Instant Micro-deposit events  When a user goes through the Instant Micro-deposit flow, the session will have the `TRANSITION_VIEW` (`view_name = NUMBERS`) event and a `TRANSITION_VIEW` (`view_name = INSTANT_MICRODEPOSIT_AUTHORIZED`) event after the user authorizes Plaid to send a micro-deposit to the submitted account and routing number. In the `onSuccess` callback the `verification_status` will be `manually_verified` since, unlike Same Day Micro-deposits, Instant Micro-deposits will resolve to either a success or fail state within a single Link session. ##### Testing the Instant Micro-deposit flow  For credentials that can be used to test Instant Micro-deposits in Sandbox, see [Auth testing flows](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-instant-micro-deposits) . #### Automated Micro-deposits  Integrate the automated micro-deposit method [View guide](https://plaid.com/docs/auth/coverage/automated/index.html.md) #### Same Day Micro-deposits  Integrate the manual micro-deposit method [View guide](https://plaid.com/docs/auth/coverage/same-day/index.html.md) #### Testing in Sandbox  Learn how to test each Auth method in the Sandbox [View guide](https://plaid.com/docs/auth/coverage/testing/index.html.md) --- # Auth - Micro-deposit Events | Plaid Docs Micro-deposit events  ===================== #### Learn how to use Bank Transfers webhooks to receive micro-deposit status updates  #### Overview  If you are using the optional [Same Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) verification method for Auth and want to receive updates on the state of your micro-deposit transfers, you can enable webhooks for Bank Transfer events that notify you of transfer status updates for Plaid-initiated transfers within the ACH network. #### Bank Transfers webhooks  To enable Bank Transfers webhooks, add your endpoint on the [account webhooks](https://dashboard.plaid.com/developers/webhooks) page of the dashboard. You will need to have received production approval for Auth before being able to add an endpoint. Bank Transfers webhooks are not part of Plaid's [Transfer](https://plaid.com/docs/transfer/index.html.md) product. All Auth customers have access to Bank Transfer webhooks; it is not required to sign up for Plaid Transfer to use these webhooks. To confirm that your endpoint has been correctly configured, you can trigger a test webhook via [/sandbox/bank\_transfer/fire\_webhook](https://plaid.com/docs/bank-transfers/reference/index.html.md#sandboxbank_transferfire_webhook) . You should receive the payload body specified below. Bank Transfers webhook body ```json { "webhook_type": "BANK_TRANSFERS", "webhook_code": "BANK_TRANSFERS_EVENTS_UPDATE" } ``` Once you have enabled Bank Transfers webhooks, the [/bank\_transfer/event/sync](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventsync) endpoint can be called to discover new ACH events. To know when you should call this endpoint, listen for the [BANK\_TRANSFERS\_EVENTS\_UPDATE](https://plaid.com/docs/bank-transfers/reference/index.html.md#bank_transfers_events_update) webhook. You will receive a Bank Transfers webhook any time you have posted or returned ACH micro-deposit events available. You can also search or filter micro-deposit events using the [/bank\_transfer/event/list](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventlist) endpoint. Bank Transfers webhooks and the Bank Transfers endpoint will reflect any micro-deposit sent by Plaid, including both Same Day Micro-deposits and Automated Micro-deposits, if enabled. Bank Transfers webhooks and endpoints will only reflect data about ACH events initiated through Plaid. They do not reflect other ACH activity on a linked account. #### Event types  Once your user successfully completes the micro-deposit Link flow, you will receive an `account_id` in the success callback. Bank Transfers events also contain an `account_id`, which you should use to connect events to the corresponding user. ##### Pending  A pending event type means that we have a record of the micro-deposit in our systems, but it has not yet been sent. You may assume that micro-deposits are in a pending state once you [exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) the corresponding Item's public token for an access token. Note that Plaid does not send webhooks for new pending events, but you will still see pending events in event sync responses. Example pending event ```json { "account_id": "3MqrrrP5pWUGgmnvaQlPu19R6DvwPRHwNbLr9", "bank_transfer_amount": "0.01", "bank_transfer_id": "5645fe0e-bd5e-d8da-828b-e2c7540c69d8", "bank_transfer_iso_currency_code": "USD", "bank_transfer_type": "credit", "direction": "outbound", "event_id": 5, "event_type": "pending", "failure_reason": null, "origination_account_id": null, "receiver_details": null, "timestamp": "2021-03-22T18:52:02Z" } ``` ###### Recommended action  No action needed ##### Posted  For successful micro-deposit transfers, `posted` events are the terminal event type, and no more events will be issued. Note that the end user may not receive the micro-deposit until several banking hours after the `posted` event. In addition, a `posted` event does not guarantee that the micro-deposit was successful; if the micro-deposit fails, a `reversed` event will eventually occur some time after the `posted` event. Example posted event ```json { "account_id": "3MqrrrP5pWUGgmnvaQlPu19R6DvwPRHwNbLr9", "bank_transfer_amount": "0.01", "bank_transfer_id": "5645fe0e-bd5e-d8da-828b-e2c7540c69d8", "bank_transfer_iso_currency_code": "USD", "bank_transfer_type": "credit", "direction": "outbound", "event_id": 5, "event_type": "posted", "failure_reason": null, "origination_account_id": null, "receiver_details": null, "timestamp": "2021-03-22T18:52:02Z" } ``` ###### Recommended Action  If the micro-deposit succeeds, all posted transfers will land in the end user's account by 8:30am EST on the following banking day. After the micro-deposit settlement time, Plaid recommends sending the end user an alert (through SMS, email, or push notification) to verify the micro-deposit amounts. If you have enabled both Same Day and Automated micro-deposits, then before notifying the user, you should first confirm that the event corresponds to a Same Day micro-deposit by checking that the verification status is `pending_manual_verification` (and not `pending_automatic_verification`, which would correspond to an Automated Micro-deposit). Because Plaid handles Automated Micro-deposits without user interaction, it is not necessary to prompt the user during the Automatic Micro-deposit flow. If you have not already stored the verification status, you can obtain it by calling [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) . ##### Reversed  A `reversed` event indicates that a micro-deposit attempt has failed. Reversed events will contain an [ACH return code](https://plaid.com/docs/errors/transfer/index.html.md#ach-return-codes) that indicates why the micro-deposit failed. Example reversed event ```json { "account_id": "bV8WNn73rLI5Ln1MmdErsDn9jv7w37uGMaQvP", "bank_transfer_amount": "0.01", "bank_transfer_id": "826712b2-c707-cf98-5ba9-13bd3cc2b2f0", "bank_transfer_iso_currency_code": "USD", "bank_transfer_type": "credit", "direction": "outbound", "event_id": 5, "event_type": "reversed", "failure_reason": { "ach_return_code": "R03", "description": "No account or unable to locate account" }, "origination_account_id": null, "receiver_details": null, "timestamp": "2021-03-25T21:35:47Z" } ``` ###### Recommended Action  Contact the user with a notification that authentication has failed. Once they return to your application, restart the Link flow to begin another authentication attempt. --- # Auth - Anti-fraud best practices | Plaid Docs Anti-fraud best practices  ========================== #### Optimally configure manual entry verification methods to reduce fraud  Plaid provides a suite of fraud prevention products that assist your application in catching bad actors and ACH returns. You can verify the source of funds with [Identity](https://plaid.com/docs/identity/index.html.md) , confirm the real-time [Balance](https://plaid.com/docs/balance/index.html.md) prior to a transfer, and leverage Plaid's ML-based [Signal Transaction Scores](https://plaid.com/docs/signal/index.html.md) to prevent returns and release funds earlier. These features are fully compatible with accounts connected via Instant Auth, Instant Match, and Automated Micro-deposits. However, if an account is connected via a manual entry method such as Same Day Micro-deposits, Instant Micro-deposits, or Database Auth, or if the account type is a [limited-purpose checking account](https://plaid.com/docs/auth/index.html.md#enabling-limited-purpose-checking-accounts-for-rent-or-mortgage) , these features are not always available, which could increase the likelihood that you experience fraud and ACH returns. Following the recommendations below can help mitigate these risks. ##### Use Identity Match, Signal, and/or Identity Document Upload  Approximately 30% of Items created with manual entry methods (including 100% of Items created by Database Auth that have a `database_insights_pass` verification status) are supported by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , which allows you to determine the likelihood that the user's identity details, such as name and address, on file with their financial institution match identity information held by you. For more details on this feature, see [Identity](https://plaid.com/docs/identity/index.html.md#identity-match) . The same Items that are supported by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) are also supported by Signal Transaction Scores. Signal Transaction Scores can assess the return risk of a transaction based on machine learning analysis and alert you to high-risk transactions. For more details, see [Signal Transaction Scores](https://plaid.com/docs/signal/index.html.md) . [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) verifies account owner identity based on bank statements, and is compatible with Items that don't support [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) or [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) . After creating the Item, you can use update mode to send the user through a Link session where they will be asked to upload a bank statement. Plaid will then analyze this statement for an account number match and will parse identity data from the statement. With the optional Fraud Risk feature, you can also check the uploaded statement for signs of fraud. For more details, see [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) . Limited-purpose checking accounts, while not compatible with Balance, are compatible with Signal Transaction Scores, Identity, and Identity Match. Using some combination of these products can reduce ACH return risk when working with limited-purpose checking accounts. ##### Adjust a user's Link experience based on their risk profile  In order to reduce fraud upstream on your application, you can use [Plaid Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) to verify a government ID or match with a selfie of the document holder. If your application does not have an identity verification solution or Plaid Link is not gated from the general public with fraud prevention and user verification checks in place, we do not recommend adopting manual entry verification methods as it may introduce an unnecessary fraud vector onto your platform. If you identify a user to be riskier, consider disabling manual entry verification methods for those users. Another option for riskier users is to leave manual entry verification methods enabled, but enable [Reroute to Credentials in Forced mode](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#forced-reroute) , which will only allow the user to link via manual entry verification methods when using a routing number not supported by other authentication methods. You may also consider changing your user's experience with your service based on their connection method or available data. For example, if a user connected via a manual entry verification method, you may consider enforcing a lower transfer threshold than for users where it was possible to verify identity and increasing hold times on those funds. --- # Auth - Same Day Micro-deposits | Plaid Docs Same Day Micro-deposits  ======================== #### Learn how to authenticate your users with a manually verified micro-deposit  ### Overview  Same Day Micro-deposits can be used to authenticate any bank account in the US, but especially for the ~2,000 institutions that don't support Instant Auth, Instant Match, or Automated Micro-deposit verification. Plaid will make a deposit that will post within one business day (using Same Day ACH, which is roughly two days faster than the standard micro-deposit experience of two to three days). Users are instructed to manually verify the code in the transaction description deposited in the account. #### The Same Day Micro-deposit flow  The user clicks an action that opens Plaid Link. (An image of "The user clicks an action that opens Plaid Link.") (An image of "They optionally log in...") (An image of "...select a new institution...") (An image of "...and choose to connect by entering account numbers manually.") (An image of "The user enters their routing number...") (An image of "...account number...") (An image of "...full name...") (An image of "...selects an account type...") (An image of "...and authorizes the transfer.") (An image of "The user enters their phone number to be notified when the transfer has arrived.") (An image of "The user is told to come back in a few days.") (An image of "A day or two later, the user receives an SMS notification that the deposit has arrived.") (An image of "After getting the code from their bank account, they return to Plaid to verify the code.") (An image of "And the account is verified") A user connects their financial institution using the following connection flow: 1. Starting on a page in your app, the user clicks an action that opens Plaid Link with the correct Auth [configuration](https://plaid.com/docs/auth/coverage/same-day/index.html.md#create-a-link_token) . 2. Inside of Plaid Link, the user enters the micro-deposit initiation flow and provides their legal name, account and routing number. 3. Upon [successful authentication](https://plaid.com/docs/auth/coverage/same-day/index.html.md#exchange-the-public-token) , Link closes with a `public_token` and a `metadata` account status of `pending_manual_verification`. 4. Behind the scenes, Plaid sends a micro-deposit to the user's account that will post within one to two business days. 5. After one to two days, the user is prompted to verify the code in the transaction description in their account, by [opening Link with a generated link\_token](https://plaid.com/docs/auth/coverage/same-day/index.html.md#prompt-user-to-verify-micro-deposit-code-in-link) . Plaid will not reverse the $0.01 micro-deposit credit. When these steps are done, your user's Auth data is verified and [ready to fetch](https://plaid.com/docs/auth/coverage/same-day/index.html.md#fetch-auth-data) . ##### Demoing the flow in Link  You can try out the Same Day Micro-deposits flow in an [Interactive Demo](https://plaid.coastdemo.com/share/67d0ce0df465686c02cc4fd2?zoom=100&step=9) . For more details, see the [testing guide](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-same-day-micro-deposits) . #### Implementation steps  ##### Enable Same Day micro-deposits  Enable Same Day micro-deposits via the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) . Alternatively, you can also enable it by setting the `auth.same_day_microdeposits_enabled: true` parameter when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . ##### Create a link\_token  Create a `link_token` with the following parameters: * `products` array should include only `auth` or `transfer` as a product when using same-day manual micro-deposit verification. While in most cases additional products can be added to existing Plaid Items, Items created for Same Day manual micro-deposit verification are an exception and cannot be used with any Plaid products other than Auth or Transfer. Approximately 30% of Items verified by Same Day micro-deposits can also be verified by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) or [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) . If using Identity Match or Signal Transaction Scores in this way, they should be added to the Item via the `required_if_supported_products`, `optional_products`, or `additional_consented_products` fields rather than the `products` array. For more details, see [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) and [Signal Transaction Scores](https://plaid.com/docs/signal/signal-rules/index.html.md#data-availability-limitations) . All Items verified by Same Day micro-deposits are also compatible with statement-based verification via [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) . * `country_codes` set to `['US']` – Micro-deposit verification is currently only available in the United States. ##### Initialize Link with a link\_token  After creating a `link_token` for the `auth` product, use it to initialize Plaid Link. When the user successfully inputs their account and routing numbers, the `onSuccess()` callback function (or the equivalent field in [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) , if using the [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) integration method) will return a `public_token`, with `verification_status` equal to `'pending_manual_verification'`. App.js ```javascript const linkHandler = Plaid.create({ // Fetch a link_token configured for 'auth' from your app server token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token and connected accounts to your app server $.post('/exchange_public_token', { publicToken: public_token, accounts: metadata.accounts, }); metadata = { ..., link_session_id: String, institution: { name: null, // name is always null for Same Day Micro-deposits institution_id: null // institution_id is always null for Same Day Micro-deposits }, accounts: [{ id: 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D', mask: '1234', name: "Checking...1234", type: 'depository', subtype: 'checking', verification_status: 'pending_manual_verification' }] } }, // ... }); // Open Link on user-action linkHandler.open(); ``` ##### Display a "pending" status in your app  Because Same Day verification usually takes one business day to complete, we recommend displaying a UI in your app that communicates to a user that verification is currently pending. You can use the `verification_status` key returned in the `onSuccess` `metadata.accounts` object once Plaid Link closes successfully. Metadata verification\_status ```javascript verification_status: 'pending_manual_verification'; ``` You can also [fetch the verification\_status](https://plaid.com/docs/auth/coverage/same-day/index.html.md#check-the-account-verification-status-optional) for an Item's account via the Plaid API, to obtain the latest account status. ##### Exchange the public token  In your own backend server, call the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint with the Link `public_token` to obtain an `access_token`. When using same-day micro-deposit verification, only one account can be associated with each access token. If you want to allow a user to link multiple accounts at the same institution using same-day micro-deposits, you will need to create a new Link flow and generate a separate access token for each account. To test your integration outside of Production, see [Testing Same Day Micro-deposits in Sandbox](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-same-day-micro-deposits) . ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" }' ``` ```node // publicToken and accountID are sent from your app to your backend-server const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D'; const publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d'; // Obtain an access_token from the Link public_token try { const response = await client.itemPublicTokenExchange({ public_token: publicToken, }); const accessToken = response.data.access_token; } catch (err) { // handle error } ``` ```python # publicToken and accountID are sent from your app to your backend-server accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D' publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' # Obtain an access_token from the Link public_token token_request = ItemPublicTokenExchangeRequest( public_token=publicToken) token_response = client.item_public_token_exchange(token_request) accessToken = token_response['access_token'] ``` ```ruby # publicToken and accountID are sent from your app to your backend-server accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D' publicToken = 'public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d' # Obtain an access_token from the Link public_token request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: publicToken } ) token_response = client.item_public_token_exchange(request) access_token = token_response.access_token ``` ```java // publicToken and accountID are sent from your app to your backend-servers String accountID = "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"; String publicToken = "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"; // Obtain an access_token from the Link public_token ItemPublicTokenExchangeRequest tokenRequest = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response tokenResponse = plaidClient .itemPublicTokenExchange(tokenRequest) .execute(); String accessToken = tokenResponse.body().getAccessToken(); ``` ```go // publicToken and accountID are sent from your app to your backend-server accountID := "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D" publicToken := "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" // Obtain an access_token from the Link public_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest(publicToken), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() ``` Exchange token response ```json { "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755", "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op", "request_id": "m8MDnv9okwxFNBV" } ``` ##### Check the account verification status (optional)  In some cases you may want to implement logic in your app to display the `verification_status` of an Item that is pending manual verification. The [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) API endpoint allows you to query this information. To be notified via webhook when Plaid has sent the micro-deposit to your end user, see [micro-deposit events](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) . ```bash curl -X POST https://sandbox.plaid.com/accounts/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755" }' ``` ```node // Fetch the accountID and accessToken from your database const accountID = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D'; const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755'; const request: AccountsGetRequest = { access_token: accessToken, }; try { const response = await client.accountsGet(request); const account = response.data.accounts.find((a) => a.account_id === accountID); const verificationStatus = account.verification_status; } catch (err) { // handle error } ``` ```python # Fetch the accountID and accessToken from your database account_id = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D' access_token = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755' request = AccountsGetRequest(access_token=access_token) response = client.accounts_get(request) accounts = response['accounts'] ``` ```ruby # Fetch the accountID and accessToken from your database account_id = 'vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D' access_token = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755' request = Plaid::AccountsGetRequest.new({ access_token: access_token }) response = client.accounts_get(request) accounts = response.accounts ``` ```java // Fetch the accountID and accessToken from your database String accountID = "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"; String accessToken = "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755"; AccountsGetRequest request = new AccountsGetRequest() .accessToken(accessToken); Response response = client() .accountsGet(request) .execute(); if (response.isSuccessful()) { AuthGetNumbers numbers = response.body().getNumbers(); } ``` ```go // Fetch the accountID and accessToken from your database accountID := "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D" accessToken := "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755" accountsGetResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest( *plaid.NewAccountsGetRequest(accessToken), ).Execute() accounts := accountsGetResp.GetAccounts() ``` Account get response ```json { "accounts": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "balances": { Object }, "mask": "0000", "name": "Checking...0000", "official_name": null, "type": "depository", "subtype": "checking", "verification_status": "pending_manual_verification" | "manually_verified" | "verification_failed" }, ... ], "item": { Object }, "request_id": String } ``` ##### Prompt user to verify micro-deposit code in Link  After one to two business days, the micro-deposit sent to the user's account is expected to be posted. To securely verify a Same Day Micro-deposits account, your user needs to come back into Link to verify the code in the transaction description. When the micro-deposit posts to your end user's bank account, the transaction description will be written with the format: Micro-deposit post description ```bash #XXX ACCTVERIFY ``` The `#` will be followed with the three letter code required for verification. The `` is defined by the value of the `client_name` parameter that was used to create the `link_token` that initialized Link. Due to network requirements, the `client_name` will be truncated to the first 11 characters and `ACCTVERIFY` will be added to signify the deposit is for account verification. Users with business or corporate accounts that have ACH debit blocks enabled on their account may need to authorize Plaid's Company / Tax ID, `1460820571`, to avoid any issues with linking their accounts. To optimize conversion, we strongly recommend sending your user a notification (e.g. email, SMS, push notification) prompting them to come back into your app and verify the micro-deposit code. To be notified via webhook when Plaid has sent the micro-deposit to your end user, see [micro-deposit events](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) . (An image of "Plaid Instant Match process: Enter 3-letter code from deposit, confirmation screen, success message linking to Wonderwallet.") Verification of Same Day Micro-deposits is performed in two steps: 1. In your backend server, create a new `link_token` from the associated `access_token` for the given user. 2. Pass the generated `link_token` into your client-side app, using the `token` parameter in the Link configuration. This will automatically trigger the micro-deposit verification flow in Link. ##### Create a new link\_token from a persistent access\_token  Generate a `link_token` for verifying micro-deposits by passing the user's associated `access_token` to the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) API endpoint. Note that the `products` field should not be set because the micro-deposits verification flow does not change the products associated with the given `access_token`. ```node // Using Express app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { client_user_id: clientUserId, }, client_name: 'Plaid Test App', language: 'en', webhook: 'https://webhook.sample.com', country_codes: [CountryCode.Us], access_token: 'ENTER_YOUR_ACCESS_TOKEN', }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "access_token": "${ACCESS_TOKEN}", "country_codes": ["US"], "language": "en", "webhook": "https://webhook.sample.com" }' ``` ```ruby require 'sinatra' require 'plaid' post '/api/create_link_token' do // Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user => { client_user_id: client_user_id }, client_name: 'Plaid Test App', access_token: 'ENTER_YOUR_ACCESS_TOKEN', country_codes: ['US'], language: "en", webhook: 'https://webhook.sample.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; static class GetLinkToken implements HttpHandler { private static PlaidClient plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Simplified pseudo-code for obtaining a user_id User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .accessToken("ENTER_YOUR_ACCESS_TOKEN") .countryCodes(Arrays.asList(CountryCode.US, CountryCode.CA)) .language("en") .redirectUri(redirectUri) .webhook("https://sample.webhook.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } ``` ```python # Using Flask @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( access_token ="ENTER_YOUR_ACCESS_TOKEN", client_name="Plaid Test App", country_codes=[CountryCode('US')], language='en', webhook='https://webhook.sample.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) link_token = response['link_token'] # Send the data to the client return jsonify(response.to_dict()) ``` ```go import ( "context" "net/http" "os" "github.com/gin-gonic/gin" "github.com/plaid/plaid-go/plaid" ) func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetAccessToken("ENTER_YOUR_ACCESS_TOKEN") resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` ##### Initialize Link with the generated link\_token  In your client-side app, pass the generated `link_token` into the Link `token` parameter. Link will automatically detect that Same Day verification is required for the Item and will open directly into the verification flow (see the image above). In Link, the user will be prompted to log in to their personal banking portal to confirm the code in the micro-deposit transaction description. Upon successful entry of the code, the `onSuccess` callback will be fired, with an updated `verification_status: 'manually_verified'`. The verification code will be case-insensitive. There is no time limit for the user to verify the deposit. A user has three attempts to enter the code correctly, after which the Item will be permanently locked for security reasons. See [INCORRECT\_DEPOSIT\_VERIFICATION](https://plaid.com/docs/errors/invalid-input/index.html.md#incorrect_deposit_verification) and [PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/item/index.html.md#product_not_ready) for errors that may occur during the micro-deposit initiation and verification flow. App.js ```javascript const linkHandler = Plaid.create({ token: await fetchLinkTokenForMicrodepositsVerification(), onSuccess: (public_token, metadata) => { metadata = { accounts: [{ ..., verification_status: 'manually_verified', }], }; }, // ... }); // Open Link to verify micro-deposit amounts linkHandler.open(); ``` An Item's `access_token` does not change when verifying micro-deposits, so there is no need to repeat the exchange token process. ##### Fetch Auth data  Finally, we can retrieve Auth data once the user has manually verified their account through Same Day Micro-deposits: ```bash curl -X POST https://sandbox.plaid.com/auth/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755" }' ``` ```node const accessToken = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755'; // Instantly fetch Auth numbers const request: AuthGetRequest = { access_token: accessToken, }; try { const response = await client.authGet(request); const numbers = response.data.numbers; } catch (err) { // handle error } ``` ```python access_token = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755' # Instantly fetch Auth numbers auth_request = AuthGetRequest(access_token=access_token) auth_response = client.auth_get(auth_request) numbers = auth_response['numbers'] ``` ```ruby access_token = 'access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755'; # Instantly fetch Auth numbers auth_get_request = Plaid::AuthGetRequest.new auth_get_request.access_token = access_token auth_response = client.auth_get(auth_get_request) numbers = auth_response.numbers ``` ```java String accessToken = "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755"; // Instantly fetch Auth numbers AuthGetRequest authGetRequest = new AuthGetRequest() .accessToken(accessToken); Response authResponse = client() .authGet(authGetRequest) .execute(); if (authResponse.isSuccessful()) { AuthGetResponse.Numbers numbers = authResponse.body().getNumbers(); } ``` ```go accessToken := "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755" // Instantly fetch Auth numbers authGetResp, _, err := client.PlaidApi.AuthGet(ctx).AuthGetRequest( *plaid.NewAuthGetRequest(accessToken), ).Execute() numbers := authGetResp.GetNumbers() ``` Auth response ```json { "numbers": { "ach": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "account": "1111222233330000", "routing": "011401533", "wire_routing": "021000021" } ], "eft": [], "international": [], "bacs": [] }, "accounts": [ { "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D", "balances": { Object }, "mask": "0000", "name": "Checking ...0000", "official_name": null, "verification_status": "manually_verified", "subtype": "checking", "type": "depository" } ], "item": { Object }, "request_id": "m8MDnv9okwxFNBV" } ``` Check out the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) API reference documentation to see the full Auth request and response schema. #### Using Text Message Verification  Text Message Verification is an alternative verification method for Same Day Micro-deposits. With Text Message Verification, Plaid will send your user a one-time SMS message, directing them to a Plaid-hosted website where they can complete the micro-deposit verification process. When the user is done verifying their micro-deposit code, you will receive a [SMS\_MICRODEPOSITS\_VERIFICATION](https://plaid.com/docs/api/products/auth/index.html.md#sms_microdeposits_verification) webhook, telling you that the user has completed the process and that it is now safe to retrieve Auth information. Text Message Verification can and should be used alongside the usual verification flow of prompting your user to verify their code inside your app through Link. The user may not be prompted to receive the SMS message (if they clicked "continue as guest"), may choose not to receive an SMS message, or they might simply ignore the message, so it is important for your app to still provide a way for your user to complete the process. ##### Implementation steps  Text Message Verification is enabled by default as long as Same Day Micro-deposits have been enabled. To opt out of Text Message Verification, use the [Dashboard Account Verification pane](https://dashboard.plaid.com/account-verification) to disable it, or, if not using the Account Verification Dashboard, set `auth.sms_microdeposits_verification_enabled: false` in your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. 1. When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , make sure you have specified a URL for your webhook receiver, so you can receive the [SMS\_MICRODEPOSITS\_VERIFICATION](https://plaid.com/docs/api/products/auth/index.html.md#sms_microdeposits_verification) webhook. 2. Listen for the [SMS\_MICRODEPOSITS\_VERIFICATION](https://plaid.com/docs/api/products/auth/index.html.md#sms_microdeposits_verification) webhook. When the user completes the verification process, Plaid will send a [SMS\_MICRODEPOSITS\_VERIFICATION](https://plaid.com/docs/api/products/auth/index.html.md#sms_microdeposits_verification) webhook to the webhook receiver URL that you specified earlier. When you receive this webhook, review the value of the `status` field. Example webhook ```json { "webhook_type": "AUTH", "webhook_code": "SMS_MICRODEPOSITS_VERIFICATION", "status": "MANUALLY_VERIFIED", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "environment": "sandbox" } ``` A value of `MANUALLY_VERIFIED` indicates that the user successfully entered the micro-deposit code and has verified their account information. You can now retrieve Auth information on behalf of this user, and you should remove any pending in-app messages asking the user to complete the verification process. If you re-open Link and ask the user to verify their code after they have already verified it using Text Message Verification, Link will close immediately and fire the `onSuccess` callback. So even if you don't act on this webhook, your application will continue to function normally. A `status` field of `VERIFICATION_FAILED` indicates that the user failed the verification process. Verification cannot be retried once this status has been triggered; you will need to create a new Item. ##### User experience  When the user goes through the Same Day Micro-deposit flow in Link, they will be prompted to enter their phone number, as long as they did not opt out of using or creating a Plaid account. Users who skip the Plaid account process and click "Continue as guest" instead will not be prompted to enter their phone number and cannot participate in Text Message Verification. After the micro-deposit has been placed in their account, if the user authorized Plaid to send the text message, Plaid will contact the user via SMS with a URL pointing to a Plaid-hosted page where the user can complete the verification process. The text message itself will contain the following message: Sample SMS message ```bash Plaid: On behalf of [client_name], a $0.01 deposit was sent to your account ending in 1234. Verify this deposit here: https://hosted.plaid.com/link/lp1234. Then, return to [client_name] to complete your account setup. ``` Currently, the text message is only provided in English and will not be localized according to your Link customization settings. ##### Testing text message verification  Text message verification cannot be tested in the Sandbox environment. Text messages will only be sent in Production, and will only be sent to users who do not click "Continue as guest" on the Link consent pane. #### Same Day Micro-deposit flow configuration options  In addition to the default flow, Same Day Micro-deposits has several optional flow settings you can enable. To expose more users to the Same Day micro-deposit flow, you can enable [Auth Type Select](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#adding-manual-verification-entry-points-with-auth-type-select) , or to limit users' exposure to the flow, you can enable [Reroute to Credentials](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#removing-manual-verification-entry-points-with-reroute-to-credentials) . To provide an alternative flow that allows users to skip micro-deposit verification and instead relies on recognizing a known bank account within the Plaid network, you can enable [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) . The setting that is best for you will depend on your use case, your risk exposure, and which other Plaid products you use. Learn more about how to optimize your configuration and manage risk under [best practices](https://plaid.com/docs/auth/coverage/same-day-link-best-practices/index.html.md) . Same Day Micro-deposit flow options are configured on a Link customization level (if using the Account Verification Dashboard) or on a Link token level (if configuring the options directly in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call). This enables you to decide which sessions are enabled for which flows; for example, you can enable different verification methods based on users' risk profiles. #### Handling Link events  When a user goes through the Same Day micro-deposits flow, the session will have the `TRANSITION_VIEW (view_name = NUMBERS)` event and a `TRANSITION_VIEW` (`view_name = SAME_DAY_MICRODEPOSIT_AUTHORIZED`) event after the user authorizes Plaid to send a micro-deposit to the submitted account and routing number. In the `onSuccess` callback the `verification_status` will be `pending_manual_verification` because the user will have to return to Link to verify their micro-deposit at a later Link session. Sample Link events for Same Day micro-deposits where user enters flow from empty Search state ```bash OPEN (view_name = CONSENT) TRANSITION_VIEW (view_name = SELECT_INSTITUTION) SEARCH_INSTITUTION TRANSITION_VIEW (view_name = NUMBERS) TRANSITION_VIEW (view_name = LOADING) TRANSITION_VIEW (view_name = CONNECTED) HANDOFF onSuccess (verification_status: pending_manual_verification) ``` When a user goes through the Same Day micro-deposits flow with Reroute to Credentials, you will additionally see `TRANSITION_VIEW (view_name = NUMBERS_SELECT_INSTITUTION)` with `view_variant = SINGLE_INSTITUTION` or `view_variant = MULTI_INSTITUTION`. Sample Link events for Same Day micro-deposits flow where user encounters Reroute to Credentials ```bash OPEN (view_name = CONSENT) TRANSITION_VIEW (view_name = SELECT_INSTITUTION) SEARCH_INSTITUTION TRANSITION_VIEW (view_name = NUMBERS) TRANSITION_VIEW (view_name = NUMBERS_SELECT_INSTITUTION, view_variant = SINGLE_INSTITUTION) TRANSITION_VIEW (view_name = LOADING) TRANSITION_VIEW (view_name = CONNECTED) HANDOFF onSuccess (verification_status: pending_manual_verification) ``` When a user goes through the Same Day micro-deposits flow with the Auth Type Select configuration, you will additionally see `TRANSITION_VIEW (view_name = SELECT_AUTH_TYPE)` and also `SELECT_AUTH_TYPE (selection = flow_type_manual)` Sample Link events for Same Day micro-deposits flow where user enters flow from Auth Type Select ```bash OPEN (view_name = CONSENT) TRANSITION_VIEW (view_name = SELECT_AUTH_TYPE) SELECT_AUTH_TYPE (selection = flow_type_manual) TRANSITION_VIEW (view_name = NUMBERS) TRANSITION_VIEW (view_name = LOADING) TRANSITION_VIEW (view_name = CONNECTED) HANDOFF onSuccess (verification_status: pending_manual_verification) ``` #### Testing in Sandbox  Learn how to test each Auth flow in the Sandbox [View guide](https://plaid.com/docs/auth/coverage/testing/index.html.md) #### Manual verification flow best practices  Minimize fraud by following best practices [View guide](https://plaid.com/docs/auth/coverage/same-day-link-best-practices/index.html.md) #### Micro-deposit events  Learn how to use webhooks to receive micro-deposit status updates [View guide](https://plaid.com/docs/auth/coverage/microdeposit-events/index.html.md) --- # Auth - Test in Sandbox | Plaid Docs Testing Auth methods  ===================== #### Testing Instant Match, Database Auth, and micro-deposit flows  #### Sandbox configuration  To test in the [Sandbox environment](https://plaid.com/docs/sandbox/index.html.md) , you need to set the Link configuration environment to `"sandbox"`: App.js ```javascript Plaid.create({ // ... env: 'sandbox', }); ``` You will also want to direct any backend API requests to the sandbox URL: API host ```xml https://sandbox.plaid.com ``` #### Testing Instant Match  ##### Test credentials  | Sandbox input | Successful credentials | Erroneous credentials | | --- | --- | --- | | Institution Name | Houndstooth Bank (`ins_109512`) | –– | | Username | `user_good` | –– | | Password | `pass_good` | –– | | Account Selection | `Plaid Savings (****1111)` | –– | | Routing number | `021000021` | Any other routing number | | Account number | `1111222233331111` | Any other account number | ##### Entering the Link flow  * Search for "Houndstooth Bank" in Link. * Use the input data in the table above to simulate the desired outcome. #### Testing Instant Micro-deposits  You can also test this flow in Sandbox with no code by using the [Link Demo](https://plaid.com/link-demo) . | Sandbox input | Successful credentials | Erroneous credentials | | --- | --- | --- | | Institution name | Windowpane Bank (`ins_135858`) | –– | | Routing number | `333333334` | Any other value (if testing upgrade path) | | Account number | `1111222233330000` | –– | | Deposit code | `ABC` | Any other value | ##### Entering the primary Link flow  * Search for "Windowpane Bank" in Link. * When prompted, use the input data in the table above to simulate the desired outcome. * For all other fields, you can use any values. ##### Testing the upgrade path from Same Day Micro-deposits to Instant Micro-deposits  * If you have enabled Same Day Micro-deposits, enter gibberish into the search bar to ensure no institutions will be found, then click on Link with account numbers. * If you have configured Same Day Micro-deposits with Auth Type Select, choose "Manually" from the menu. * When prompted, enter the input data in the table above. For all other fields, you can use any values. * Note that, unlike the primary Instant Micro-deposits flow, the routing and account number entries will be on separate panes. #### Testing Database Auth or Database Insights  You can also test this flow in Sandbox with no code by using the [Link Demo](https://plaid.com/link-demo) . ##### Test credentials (US-based sessions)  To simulate a `database_insights_pass` result: | Sandbox input | Credentials | | --- | --- | | Routing number | Any routing number (e.g. `110000000`) | | Account number | `1111222233331111` | To simulate a `database_insights_pass_with_caution` result: | Sandbox input | Credentials | | --- | --- | | Routing number | Any routing number (e.g. `110000000`) | | Account number | `1111222233333333` | Any other account number will simulate a `database_insights_fail` result, e.g.: | Sandbox input | Credentials | | --- | --- | | Routing number | Any routing number (e.g. `110000000`) | | Account number | `1111222233332222` | To simulate a 100 name match score, use the name "John Smith". ##### Test credentials (CA-based sessions)  To simulate a `database_insights_pass` result: | Sandbox input | Credentials | | --- | --- | | Institution number | `110` | | Branch number | `11111` | | Account number | `11223311` | To simulate a `database_insights_pass_with_caution` result: | Sandbox input | Credentials | | --- | --- | | Institution number | `110` | | Branch number | `11111` | | Account number | `11223333` | Any other input will simulate a `database_insights_fail` result, e.g.: | Sandbox input | Credentials | | --- | --- | | Institution number | `110` | | Branch number | `11111` | | Account number | `11223322` | To simulate a 100 name match score, use the name "John Smith". ##### Entering the Link flow  * If you have configured Database Auth or Database Insights with Auth Type Select, choose "Manually" from the menu. * If you have configured Database Auth or Database Insights with Embedded Search, choose "Connect Manually". * If you have enabled Database Auth or Database Insights without either of the above options, enter gibberish into the search bar to ensure no institutions will be found, then click on "Link with account numbers". * Use input data from the table above to simulate various outcomes. #### Testing Automated Micro-deposits  You can also test this flow in Sandbox with no code by using the [Link Demo](https://plaid.com/link-demo) . ##### Test credentials  | Sandbox input | Successful credentials | Erroneous credentials | | --- | --- | --- | | Institution Name | Houndstooth Bank (`ins_109512`) | –– | | Username | `user_good` | –– | | Password | `microdeposits_good` | –– | | Account Selection | `Plaid Checking (****0000)` | –– | | Routing number | `021000021` | Any other routing number | | Account number | `1111222233330000` | Any other account number | ##### Entering the Link flow  * Search for "Houndstooth Bank" in Link. * Use the input data in the table above to simulate the desired outcome. The micro-deposit verification will automatically succeed after twenty-four hours. To test a failed micro-deposit, or to skip the twenty-four hour waiting period, use the [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) endpoint to manually control the Item's micro-deposit verification status. #### Testing Same Day Micro-deposits  You can also test this flow with no code by using the [Link Demo](https://plaid.com/link-demo) . ##### Test credentials  | Sandbox input | Successful credentials | Erroneous credentials | | --- | --- | --- | | Routing number | `110000000` | –– | | Account number | `1111222233330000` | –– | | Deposit code | `ABC` | Any other value | ##### Initiating micro-deposits in Link  * If you have configured Same Day Micro-deposits with Auth Type Select, choose "Manually" from the menu * If you have enabled Same Day Micro-deposits without Auto Type Select, enter gibberish into the search bar to ensure no institutions will be found, then click on "Link with account numbers". * Use the input data in the table above to simulate the desired outcome. ##### Verifying micro-deposits in Link  * Call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) with your `public_token` from the Link session in previous step to receive an `access_token`. * Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and provide the `access_token` from the previous step to receive a `link_token`. * Open Link with your `link_token`. * In the deposit code field, enter `ABC` #### Testing micro-deposit events  Micro-deposits that are generated in Sandbox will never be posted by default. In order to generate a posted event that you can see when you query [/bank\_transfer/event/sync](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventsync) , you can use the [/sandbox/bank\_transfer/simulate](https://plaid.com/docs/bank-transfers/reference/index.html.md#sandboxbank_transfersimulate) endpoint. Simulating a posted event in Sandbox does not generate a webhook. You will need to call [/sandbox/bank\_transfer/fire\_webhook](https://plaid.com/docs/bank-transfers/reference/index.html.md#sandboxbank_transferfire_webhook) each time you want a webhook to be published for testing. #### Testing Identity Match with Same Day micro-deposit Items  | Sandbox input | Successful credentials | Erroneous credentials | | --- | --- | --- | | Routing number | `011401533` | `110000000` | | Account number | `1111222233330000` | `1111222233330000` | | Deposit code | `ABC` | `ABC` | * Complete the Same Day Micro-deposits flow as detailed above * Call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) using any variation of data in order to test the matching algorithm * The identity data of the test user is as follows: | Field | Sandbox identity | | --- | --- | | Name | Alberta Bobbeth Charleson | | Email | [accountholder0@example.com](https://plaid.commailto:accountholder0@example.com) | | Phone | 1112223333 | | Street | 2992 Cameron Road | | City | Malakoff | | Region | NY | | Country | US | | Postal Code | 14236 | #### Testing Database Match  You can also test this flow in Sandbox with no code by using the [Link Demo](https://plaid.com/link-demo) . ##### Test credentials  To simulate a `database_matched` result: | Sandbox input | Credentials | | --- | --- | | Routing number | `110000000` | | Account number | `1111222233331111` | | Name | `John Smith` | Any other input will simulate no match and proceed with Same Day Micro-deposits, e.g.: | Sandbox input | Credentials | | --- | --- | | Routing number | `110000000` | | Account number | `1111222233332222` | | Name | `John Smith` | ##### Entering the Link flow  * If you have enabled Database Match, enter gibberish into the search bar to ensure no institutions will be found, then click on Link with account numbers. * If you have configured Database Match with Auth Type Select, choose "Manually" from the menu. * Use the input data in the table above to simulate different outcomes. --- # Auth - Introduction to Auth | Plaid Docs Introduction to Auth   ====================== #### Instantly retrieve account information to set up pay-by-bank payments via ACH and more  Get started with Auth [API Reference](https://plaid.com/docs/api/products/auth/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md) [Demo](https://plaid.coastdemo.com/share/6786ccc5a048a5f1cf748cb5?zoom=100) Auth allows you to request a user's checking, savings, or cash management account and routing number, making it easy for you to initiate credits or debits via ACH, wire transfer, or equivalent international networks. Auth makes it easy for end users to fund an account with your app, cash out to their bank account, or make purchases via pay-by-bank. To move money, Auth must be used with a payment processor: either a [Plaid Partner](https://plaid.com/docs/auth/partnerships/index.html.md) or another third party. For more information, see [Using a Payments Service](https://plaid.com/docs/auth/index.html.md#using-a-payments-service) . For an all-in-one solution that includes payment processor functionality, see [Transfer](https://plaid.com/docs/transfer/index.html.md) (US-only). For more details, see [Auth vs. Transfer comparison](https://plaid.com/docs/payments/index.html.md#auth-and-transfer-comparison) . Auth can only be used with debitable checking, savings, or cash management accounts. Credit-type accounts, including credit cards, cannot receive payments directly via electronic interbank transfers, and Auth data cannot be used to set up credit card payments. Auth can not be used to connect debit cards; instead, you can make a transfer directly from the user's bank account, saving you money over using the debit card network. [Prefer to learn by watching? Get an overview of how Auth works in just 3 minutes!](https://www.youtube.com/watch?v=2ZsANOjVjIs) Auth is commonly used in combination with other Plaid APIs that reduce risk and support compliance, such as [Balance](https://plaid.com/docs/balance/index.html.md) (to verify accounts have sufficient funds), [Signal](https://plaid.com/docs/signal/index.html.md) (to calculate the risk of ACH returns with ML-powered analysis), and [Identity](https://plaid.com/docs/identity/index.html.md) (to verify ownership information on the account). For account funding use cases, see [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) for an end-to-end KYC compliance solution with optional AML capabilities. #### Auth integration process  Below is a high level overview of the Auth integration process. For a more detailed walkthrough, see [Add auth to your app](https://plaid.com/docs/auth/add-to-app/index.html.md) or (if applicable) the docs for the specific [partner](https://plaid.com/docs/auth/partnerships/index.html.md) you are using. Embedded Link for pay-by-bank applications If your use case involves the end user choosing between paying via a credit card and paying via a bank account, it is strongly recommended to use the [Embedded experience](https://plaid.com/docs/link/embedded-institution-search/index.html.md) for Link to increase uptake of pay-by-bank. 1. Create a Link token by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with `auth` in the `products` parameter. 2. Initialize Link with the Link token from the previous step. For more details, see [Link](https://plaid.com/docs/link/index.html.md) . * For Link configuration recommendations, see [Optimizing the Link UI for Auth](https://plaid.com/docs/auth/index.html.md#optimizing-the-link-ui-for-auth) . 3. Once the user has successfully completed the Link flow, exchange the `public_token` for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . 4. If using a Plaid partner for payment processing, ensure the partner is enabled on your [Plaid Dashboard](https://dashboard.plaid.com/developers/integrations) , then call [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) to obtain a token that you will provide to the partner to enable funds transfers. For more detailed instructions, including a full walkthrough, see [Auth payment partners](https://plaid.com/docs/auth/partnerships/index.html.md) . 5. If not using a Plaid partner, call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) to obtain the account and routing number, then provide these fields to your payment processing system. 6. Listen for the [PENDING\_DISCONNECT](https://plaid.com/docs/api/items/index.html.md#pending_disconnect) webhook. If you receive it, send the Item through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . If update mode is not completed for the Item within 7 days of webhook receipt, consent will expire, which may lead to the account and routing number becoming invalid. For more details, see [PNC TAN expiration](https://plaid.com/docs/auth/index.html.md#pnc-tan-expiration) . Note that consent expiration does not result in a webhook. 7. Listen for the [USER\_PERMISSION\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) and [USER\_ACCOUNT\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) webhooks. These webhooks indicate that you must send the Item through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to refresh consent. Attempting to use the account and routing number for transactions without successfully completing update mode may result in ACH returns. For more details, see [PNC TAN expiration](https://plaid.com/docs/auth/index.html.md#pnc-tan-expiration) . 8. Implement special remediation steps for PNC Items: if the Item is at PNC and update mode has not been completed within 7 days of receiving the `PENDING_DISCONNECT` webhook as described in step 6, or if the permissions have been revoked as described in step 7, then the account and routing number will become invalid and must be regenerated. In addition to sending the Item through update mode, you must _also_ call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) , or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) , as relevant to your use case, to get a new set of routing and account numbers. To simplify your application logic, you can do this every time you send a PNC Item through update mode when using Auth. For more details, see [PNC TAN expiration](https://plaid.com/docs/auth/index.html.md#pnc-tan-expiration) . 9. (Optional) Listen for the [AUTH: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/auth/index.html.md#default_update) webhook. This webhook indicates that the routing and/or account number for an account on the Item has changed (this is very rare). Call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) , or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) on that Item, as applicable for your integration, and use only the new numbers or processor token. 10. (Optional) To enable and configure additional Auth verification flows, such as micro-deposit verification or database verification, use the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) . For demos and more information, see [Additional verification flows](https://plaid.com/docs/auth/coverage/index.html.md) . #### Using a payments service  Looking for bank-to-bank transfer capabilities and don't have a payment processor yet? Check out [Transfer](https://plaid.com/docs/transfer/index.html.md) (US only) for a money movement solution with built-in payment processing capabilities. See [Auth and Transfer comparison](https://plaid.com/docs/payments/index.html.md#auth-and-transfer-comparison) to learn more. When using Auth, you will send Auth data to a payments service to initiate an interbank transfer; Plaid does not function as the payment processor. While Plaid is processor-agnostic and allows you to work with any partner you want, one easy way to make transfers is to work with a payments platform that partners with Plaid, such as Dwolla or Square. Working with these partners, you will not call the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) endpoint, so you will not obtain a user's bank account information. Instead, you will call [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) to obtain a Plaid token that you will provide to the partner and that allows them to make these Plaid API calls as needed. For detailed instructions on how to set up Auth with a Plaid partner, as well as a list of supported funds transfer partners, see [Auth Partnerships](https://plaid.com/docs/auth/partnerships/index.html.md) . You are free to mix-and-match usage of a processor partner with your own direct usage of the Plaid API on the same linked Items. For example, if you have created a `processor_token` for a partner to use, you may choose to have this partner also perform ACH return risk assessment using the processor token. But if the partner does not provide this functionality, or you wish to do it yourself, you may do your own risk assessment by calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) directly using the Item's access token. If you choose to use a payments provider who is not a Plaid partner, you will need to obtain bank account numbers and codes directly using [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) . In the US, this data must be stored and handled in compliance with [Nacha rules](https://www.nacha.org/) ; consult your internal compliance team or the Nacha site for details. Given the sensitive nature of this information, we also recommend that you consult the [Open Finance Data Security Standard](https://ofdss.org/) for security best practices. You can also integrate with one of Plaid's [Data Security partners](https://plaid.com/partner-directory/) to process and share tokenized bank account numbers instead of raw bank account numbers. Contact your account manager to learn more about these partnerships. #### Enabling additional verification methods with the Account Verification Dashboard  Using the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) , you can customize the Auth experience to increase conversion, enabling features like micro-deposit-based verification and database verification for end users who cannot or do not want to log into their bank accounts. You can also customize when these features are presented to users. The Account Verification Dashboard also allows you to reduce account takeover fraud by incorporating [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) directly into the Link flow. For more information on the verification options you can enable via the Account Verification Dashboard, see [Additional verification methods](https://plaid.com/docs/auth/coverage/index.html.md) . You can also use the [Dashboard](https://dashboard.plaid.com/account-verification) to view the status of any completed, Auth-enabled Link session. (An image of "Session status showing Link Session ID with identity match status and auth method in Account Verification Dashboard.") The Dashboard [Account Verification analytics page](https://dashboard.plaid.com/account-verification/analytics) shows a breakdown of Auth conversion analytics by [connection method](https://plaid.com/docs/auth/coverage/index.html.md) . (An image of "image of Account Verification analytics") #### Optimizing the Link UI for Auth  By default, only checking, savings, and cash management accounts will appear when using Auth, and institutions that do not support these accounts will not appear in the Institution Select pane. The following Link configuration options are commonly used with Auth: * [Account select](https://plaid.com/docs/link/customization/index.html.md#account-select) : The "Account Select: Enabled for one account" setting configures the Link UI so that the end user may only select a single account. If you are not using this setting, you will need to build your own UI to let your end user select which linked account they want to use to send or receive funds. * [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) : This presentation mode shows the Link institution search screen embedded directly into your UI, before the end user has interacted with Link. Embedded Institution Search increases end user uptake of pay-by-bank payment methods and is strongly recommended when implementing Auth as part of a pay-by-bank use case where multiple different payment methods are supported. #### Pay by bank optimization  If you have a pay-by-bank use case, see [Increasing pay-by-bank adoption](https://plaid.com/docs/auth/pay-by-bank-ux/index.html.md) for tips on how to reduce your transaction fees by increasing the uptake of customers choosing to pay by bank. #### Tokenized account numbers  Institutions that interface with Plaid via an OAuth portal may return a tokenized account number (TAN) in the Auth response. These TANs are standard account and routing numbers that can be utilized by any ACH processor, and will be reconciled by the issuing bank on settlement. Each app a user connects to will receive a unique TAN, rather than the user's exact account number. TANs allow either the end-user or the institution itself to more rigorously monitor and even sever a specific app's ability to transfer funds. These account numbers behave differently from regular account numbers in a number of important ways. To determine if a tokenized account number is being used, use the `is_tokenized_account_number` field in the [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) response. Currently, only Chase, PNC, and US Bank use tokenized account numbers. Only the `numbers.ach.account` field can be set as a TAN (excluding brokerage or international specific numbers results). TANs are only valid for the ACH and RTP payment rails - they may not be used for wire transfers or physical checks. TANs may not be supported by your third-party fraud and account verification databases and vendors. Institutions that use TANs do not always expose them to end users; to avoid confusion, in user-facing UIs, always display the account mask rather than the account number, as end users will not recognize the issued TAN. If a user revokes access to their account (such as via the Chase Security center or [my.plaid.com](https://my.plaid.com/) ), the TAN will become invalid and any attempt to make a transfer using that TAN will fail with an R04 return code. To avoid returns, listen for the [USER\_PERMISSION\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) and [USER\_ACCOUNT\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_account_revoked) webhooks and do not use an account number, processor token, or Stripe bank account token associated with an Item or account where access has been revoked. Instead, send the end user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to restore the Item and then call the Auth endpoint again. At US Bank, TANs do not become invalid, even after Item deletion or revocation. Because account numbers alone cannot reliably be used to uniquely identify TAN-enabled accounts across different Item instances, Plaid provides a [persistent\_account\_id](https://plaid.com/docs/api/accounts/index.html.md#accounts-get-response-accounts-persistent-account-id) field for this purpose. This field is only available at institutions that use TANs. If a Chase [duplicate Item](https://plaid.com/docs/link/duplicate-items/index.html.md) is created, the old Item will be invalidated, but the TAN on the new Item will remain the same. The TAN will only change if the user revokes access. If multiple Items in your app correspond to the same account (for example, in the case of a joint bank account with multiple owners), each Item will typically have a different TAN. TANs will always be accompanied by a routing number. The TAN must be used with the routing number returned by the API. If used with a different routing number, even one associated with the same bank, the transfer may fail. In Sandbox, the Auth product results will have the `is_tokenized_account_number` boolean set to true if the Chase (`ins_56`), PNC (`ins_13`), US Bank (`ins_127990`), or the Platypus OAuth Bank (`ins_127287`) `institution_id` is set in the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) request body or the respective FIs are selected from the Sandbox Link pane. ##### PNC TAN expiration  All TAN expirations at PNC have been indefinitely postponed until further notice and are no longer scheduled to begin in January 2026. While PNC Items will still expire after one year if consent is not renewed, the TAN will continue to be valid. At PNC, any Item initialized with Auth after October 2024 will have a [consent\_expiration\_time](https://plaid.com/docs/api/products/auth/index.html.md#auth-get-response-item-consent-expiration-time) set to 1 year from the date that the user last provided consent. When the Item's consent expires, the TAN will expire as well and cannot be used to make ACH transfers. This applies regardless of how you are accessing the account numbers: via [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , via the Transfer product, or via processor tokens. You can renew consent on the Item by sending the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . You can check the Item's expiration date by calling [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) and looking for the `consent_expiration_time` field in the response. If the Item's consent had already expired when you sent the Item through update mode, you must call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) , or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) to obtain a new TAN after completing update mode, as the old TAN will not be re-activated. In addition, if the user has multiple depository accounts at PNC, then when going through the OAuth portion of the update mode flow, it's possible that they may de-select the PNC account that they originally shared with you and select a different PNC account instead. If this happens, the TAN of the account they originally shared will be invalidated. For this reason, it is recommended to call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) , or [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) _every_ time you send a PNC Item through update mode. Note that there is no additional fee for these API calls, since Auth uses a one-time fee billing model; you are only charged for your first Auth call to each Item. PNC TAN expiration does not apply to Items initialized with Auth prior to October 2024, as these Items use real account numbers rather than TANs. #### Updates to Auth data  Because routing and account numbers are inherently persistent, Plaid does not check for updates to Auth data for existing Items except in special circumstances, such as a bank changing its routing numbers due to a system change or merger. Plaid will also check for updated Auth data if a new user account is added to an Item via [update mode](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode-to-request-new-accounts) . #### Enabling limited purpose checking accounts for rent or mortgage  The instructions below are intended only for customers who receive rent or mortgage payments via Plaid Auth and who have adequate anti-fraud measures in place to allow accepting ACH payments without balance checks. To learn more, see [Anti-fraud best practices](https://plaid.com/docs/auth/coverage/same-day-link-best-practices/index.html.md) . A small number of financial institutions in the rent-tech space have limited-purpose checking accounts that can only be used for paying rent or making mortgage payments. These accounts function as a sort of virtualized ACH interface on top of an end user's funding source (usually their primary bank account). Because these accounts do not provide balance data values that correspond to funds actually available for payments, Plaid does not return balance data for this account subtype. By default, limited-purpose checking accounts cannot be added via Link. However, integrations focused on receiving rent and mortgage payments may wish to enable them. If you would like to opt in to showing them in Link, use the `account_filters` setting in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to enable limited purpose checking accounts. If enabling limited purpose checking accounts, ensure that the filter object includes _all_ account subtypes you would like to support for Auth, not just the limited purpose checking subtype. Account filters object setting to add limited purpose checking ```json "account_filters": { "depository": { "account_subtypes": [ "checking", "limited purpose checking", "savings", "cash management" ], "limited_purpose_types": ["RENT_MORTGAGE"] } } ``` To test this flow in Sandbox, use the institution "First Platypus Limited Purpose" with the username and password `user_limited_purpose_checking` / `pass_good`. Both `current_balance` and `available_balance` will be `null` for limited-purpose checking accounts. If you opt in to enabling these accounts, ensure your balance check process and/or any Signal Rules in the Dashboard are set up to allow `null` balances, and note that there may be additional risk of returned payments for these account types due to the inability to confirm funds in the account and the limited use cases of the accounts. To help manage this risk, is recommended that you have [anti-fraud measures](https://plaid.com/docs/auth/coverage/same-day-link-best-practices/index.html.md) in place. If you require a list of Plaid-supported institutions that offer limited-purpose checking accounts, contact your account manager. For Items with limited-purpose checking account types, if consent for Auth was not obtained on initial Link by adding `auth` to the `products`, `optional_products`, `required_if_supported_products`, or `additional_consented_products` array, then the Item must go through [Update Mode](https://plaid.com/docs/link/update-mode/index.html.md) to add `auth` [post-Link](https://plaid.com/docs/link/initializing-products/index.html.md) . #### United States (ACH) Auth data  The United States uses the Automated Clearing House (ACH) system for funds transfers, which uses account and routing numbers. Banks also have a second routing number, known as the wire transfer routing number. Wire transfers can be used to receive international payments and can be faster than ACH transfers, but often involve a fee. Plaid Auth can only provide wire transfer routing numbers for institutions in the US. For a detailed, comprehensive guide to ACH transfers and payments, see Plaid's [Modern Guide to ACH](https://plaid.com/solutions/ACH-guide/) . Example Auth data for US bank account ```json "numbers": { "ach": [ { "account": "1111222233330000", "account_id": "bWG9l1DNpdc8zDk3wBm9iMkW3p1mVWCVKVmJ6", "routing": "011401533", "wire_routing": "021000021" } ], "bacs": [], "eft": [], "international": [] } ``` #### Auth data for other countries  ##### Canada (EFT)  In Canada, the routing number is in a different format than US routing numbers and broken into two pieces: the transit number (also known as the branch number), followed by the institution number. Canada uses Electronic Funds Transfer (EFT); [VoPay](https://plaid.com/docs/auth/partnerships/vopay/index.html.md) is a Plaid partner that can be used to process EFT transfers. Example Auth data for Canadian bank account ```json "numbers": { "eft": [ { "account": "111122220000", "account_id": "qVZ3Bwbo5wFmoVneZxMksBvN6vDad6idkndAB", "branch": "01533", "institution": "114" } ], ... } ``` ##### Europe (SEPA transfers)  For funds transfers in Europe, also consider the [Payment Initiation API](https://plaid.com/docs/payment-initiation/index.html.md) , which allows end-to-end payments directly, without having to integrate an additional payment processor. In the European Economic Area member states (which includes Euro zone nations, as well as the United Kingdom), institutions use a Bank Identifier Code (BIC), also known as a SWIFT code. Each bank account has an International Bank Account Number (IBAN), which is used along with the BIC for funds transfers. Many bank accounts also have internal, non-IBAN account numbers that cannot be used for funds transfers. The funds transfer system is known as the Shared European Payment Area (SEPA), and it supports SEPA credit transfer, SEPA instant credit transfer, and SEPA direct debit. Example Auth data for European bank account ```json "numbers": { "international": [ { "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo", "bic": "IE64BOFI90583812345678", "iban": "IE64BOFI90583812345678" } ... ] } ``` ##### United Kingdom (BACS)  For funds transfers in the UK, also consider the [Payment Initiation API](https://plaid.com/docs/payment-initiation/index.html.md) , which allows end-to-end payments directly, without having to integrate an additional payment processor. The UK uses the SEPA system as well as the Bankers Automated Clearing System (BACS). Payments within the BACS system cannot be made outside the UK and take several days to process. BACS payments are typically used for recurring direct debit payments, such as payroll. UK bank accounts will typically have both a BACS sort code and an IBAN and support both BACS transfers and SEPA transfers. Example Auth data for UK bank account ```json "numbers": { "bacs": [ { "account": "80000000", "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo", "sort_code": "040004" } ], "international": [ { "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo", "bic": "MONZGB21XXX", "iban": "GB23MONZ04000480000000" } ] ... } ``` #### Sample app code  For a real-life example of an app that incorporates Auth, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that fetches Auth data in order to set up funds transfers. The Auth code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L81-L135) . #### Testing Auth  Plaid provides a [GitHub repo](https://github.com/plaid/sandbox-custom-users) with test data for testing Auth in Sandbox, helping you test configuration options beyond those offered by the default Sandbox user. For more information on configuring custom Sandbox data, see [Configuring the custom user account](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuring-the-custom-user-account) . For details on testing Auth with more complex Auth flows such as micro-deposit-based Auth, first familiarize yourself with [Adding Institution Coverage](https://plaid.com/docs/auth/coverage/index.html.md) , then see [Test in Sandbox](https://plaid.com/docs/auth/coverage/testing/index.html.md) . #### Auth pricing  Auth is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) . #### Next steps  Now that you understand Auth, [add Auth to your app](https://plaid.com/docs/auth/add-to-app/index.html.md) , or see [Move Money with Auth partners](https://plaid.com/docs/auth/partnerships/index.html.md) to see specific instructions for configuring Auth with Plaid partners. If you're ready to launch to Production, see the Launch Center. #### Launch Center  See next steps to launch in Production [Launch](https://dashboard.plaid.com/developers/launch-center) --- # Auth - Dwolla | Plaid Docs Add Dwolla to your app  ======================= #### Use Dwolla with Plaid Auth to send and receive payments  (An image of "Plaid and Dwolla logos, side by side.") Plaid and Dwolla have partnered to offer businesses an easier way to connect to the U.S. banking system. Plaid enables businesses to instantly authenticate a customer's bank account, giving them the ability to leverage the Dwolla API to connect to the ACH or RTP® networks for sending and receiving payments. Dwolla's solution offers frictionless ACH or real-time payments payments for companies looking to automate their current payments process and scale their business. With the Plaid + Dwolla integration, your users can verify their accounts in seconds by inputting their banking credentials in Plaid's front-end module. Plaid's mobile-friendly module handles input validation, error handling, and multi-factor authentication–providing a seamless onboarding experience to convert more users for your business. As part of the integration, Dwolla customers can access Plaid's full suite of APIs for clean, categorized transaction data, real-time balances, and more. #### Getting started  You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/docs/link/index.html.md) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. Your customers will use Link to authenticate with their financial institution and select the depository account they wish to use for ACH or RTP® transactions. From there, you'll receive a Plaid `access_token`, allowing you to leverage real-time balance checks and transaction data, and a Dwolla `processor_token`, which allows you to quickly and securely verify a bank funding source via [Dwolla's API](https://www.dwolla.com/?utm_campaign=Plaid-Documentation&utm_source=Plaid&utm_medium=Referral) without having to store any sensitive banking information. Utilizing Plaid + Dwolla enables a seamless workflow for sending and receiving payments. As a complement to this guide, you can also use [Dwolla's guide to integrating with Plaid](https://developers.dwolla.com/docs/secure-exchange/plaid) . #### Instructions  ##### Set up your Plaid and Dwolla accounts  You'll need accounts at both Plaid and Dwolla in order to use the Plaid + Dwolla integration. You'll also need to be a Dwolla customer in order to add a bank funding source. First, [sign up for a Dwolla account](https://accounts.dwolla.com/sign-up/pay-as-you-go?utm_campaign=Plaid-Documentation&utm_source=Plaid&utm_medium=Referral) if you don't already have one. Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup/dwolla) . Your account will be automatically enabled for integration access. To verify that your Plaid account is enabled for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Dwolla to enable the integration. Use the [Dwolla Sandbox](https://developers.dwolla.com/docs/testing) to test the Plaid + Dwolla integration for free. ##### Complete your Plaid application profile and company profile  After connecting your Plaid and Dwolla accounts, you'll need to complete your Plaid [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks. ##### Create a link\_token  In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. View the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) documentation for a full list of `link_token` configurations. To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) . ```node app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['auth'], language: 'en', webhook: 'https://webhook.example.com', redirect_uri: 'https://domainname.com/oauth-page.html', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "products": ["auth"], "country_codes": ["US"], "language": "en", "webhook": "https://webhook.example.com", "redirect_uri": "https://domainname.com/oauth-page.html" }' ``` ```ruby post '/api/create_link_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: client_user_id }, client_name: 'Plaid Test App', products: ['auth'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.example.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.Products; import com.plaid.client.model.CountryCode; import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; public class PlaidExample { ... static class GetLinkToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.fromValue("auth"))) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .redirectUri("https://domainname.com/oauth-page.html") .webhook("https://webhook.example.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.link_token_create_request import LinkTokenCreateRequest from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser from plaid.model.products import Products from plaid.model.country_code import CountryCode @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( products=[Products("auth")], client_name="Plaid Test App", country_codes=[CountryCode('US')], redirect_uri='https://domainname.com/oauth-page.html', language='en', webhook='https://webhook.example.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetRedirectUri("https://domainname.com/oauth-page.html") request.SetProducts([]plaid.Products{plaid.PRODUCTS_AUTH}) resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` ##### Integrate with Plaid Link  Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Dwolla `processor_token`. Integrate Link ```javascript ``` See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations. `Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe. ##### Write server-side handler  The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint. The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. In order to avoid any confusion about which account your user wishes to use with Dwolla, it is recommended to set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one account. Once you have identified the account you will use, you will send the `account_id` property of the account to Plaid, along with the `access_token`, to create a Dwolla `processor_token`. You'll send this token to Dwolla and they will use it to securely retrieve account and routing numbers from Plaid. ```bash # Exchange the public token from Plaid Link for an access token. curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "${PUBLIC_TOKEN}" }' \ -X POST \ https://sandbox.plaid.com/item/public_token/exchange # Create a processor token for a specific account id. curl \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}", "account_id": "${ACCOUNT_ID}", "processor": "dwolla" }' \ -X POST \ https://sandbox.plaid.com/processor/token/create ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; import com.plaid.client.model.ProcessorTokenCreateRequest; import com.plaid.client.model.ProcessorTokenCreateResponse; // Change sandbox to production when you're ready to go live! HashMap apiKeys = new HashMap(); apiKeys.put("clientId", plaidClientId); apiKeys.put("secret", plaidSecret); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange the public token from Plaid Link for an access token. ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response exchangeResponse = client() .itemPublicTokenExchange(request) .execute(); // Create a processor token for a specific account id. if (exchangeResponse.isSuccessful()) { String accessToken = exchangeResponse.body().getAccessToken(); ProcessorTokenCreateRequest processorRequest = new ProcessorTokenCreateRequest() .accessToken(accessToken) .processor("dwolla") .accountId("FooBarAccountId"); Response dwollaResponse = client() .processorTokenCreate(processorRequest) .execute(); if (dwollaResponse.isSuccessful()) { String dwollaProcessorToken = dwollaResponse.body().getProcessorToken(); } } ``` ```ruby require 'plaid' # Change sandbox to production when you're ready to go live! configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] =ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] configuration.api_key['Plaid-Version'] = '2020-09-14' api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) # Exchange the public token from Plaid Link for an access token. item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new item_public_token_exchange_request.public_token = public_token exchange_token_response = client.item_public_token_exchange(item_public_token_exchange_request) access_token = exchange_token_response.access_token # Create a processor token for a specific account id. processor_token_create_request = Plaid::ProcessorTokenCreateRequest.new processor_token_create_request.access_token = access_token processor_token_create_request.account_id = account_id processor_token_create_request.processor = "dwolla" create_response = client.processor_token_create(processor_token_create_request) processor_token = create_response.processor_token ``` ```python import plaid from plaid.api import plaid_api from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest from plaid.model.processor_token_create_request import ProcessorTokenCreateRequest # Change sandbox to production when you're ready to go live! configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, 'plaidVersion': '2020-09-14' } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Exchange the public token from Plaid Link for an access token. exchange_request = ItemPublicTokenExchangeRequest(public_token=public_token) exchange_token_response = client.item_public_token_exchange(exchange_request) access_token = exchange_token_response['access_token'] # Create a processor token for a specific account id. create_request = ProcessorTokenCreateRequest( access_token=access_token, account_id=account_id, processor='dwolla' ) create_response = client.processor_token_create(create_request) processor_token = create_response['processor_token'] ``` ```node const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest, } = require('plaid'); // Change sandbox to production when you're ready to go live! const configuration = new Configuration({ basePath: PlaidEnvironments[process.env.PLAID_ENV], baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, 'Plaid-Version': '2020-09-14', }, }, }); const plaidClient = new PlaidApi(configuration); try { // Exchange the public_token from Plaid Link for an access token. const tokenResponse = await plaidClient.itemPublicTokenExchange({ public_token: publicToken, }); const accessToken = tokenResponse.data.access_token; // Create a processor token for a specific account id. const request: ProcessorTokenCreateRequest = { access_token: accessToken, account_id: accountID, processor: 'dwolla', }; const processorTokenResponse = await plaidClient.processorTokenCreate( request, ); const processorToken = processorTokenResponse.data.processor_token; } catch (error) { // handle error } ``` ```go import ( "context" "os" plaid "github.com/plaid/plaid-go/v40/plaid" ) // create the client configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) // exchange the public_token for an access_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest("PUBLIC_TOKEN"), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() // get the account id accountsResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest(plaid.AccountsGetRequest{ AccessToken: accessToken, }).Execute() accountID := accountsResp.GetAccounts()[0].GetAccountId() // create a dwolla token for the specific account id request := plaid.NewProcessorTokenCreateRequest(accessToken, accountID, "dwolla") processorTokenResp, _, err := client.PlaidApi.ProcessorTokenCreate(ctx).ProcessorTokenCreateRequest( *request, ).Execute() ``` For a valid request, the API will return a JSON response similar to: ```json { "processor_token": "processor-sandbox-0asd1-a92nc", "request_id": "[Unique request ID]" } ``` ##### Make a request to Dwolla  Once you've obtained the `processor_token`, you'll then pass it to Dwolla as the value of the `plaidToken` request parameter, along with a funding source `name`, to create a funding source for a Dwolla Customer: ```bash POST https://api-sandbox.dwolla.com/customers/AB443D36-3757-44C1-A1B4-29727FB3111C/funding-sources Content-Type: application/vnd.dwolla.v1.hal+json Accept: application/vnd.dwolla.v1.hal+json Authorization: Bearer pBA9fVDBEyYZCEsLf/wKehyh1RTpzjUj5KzIRfDi0wKTii7DqY { "plaidToken": "processor-sandbox-161c86dd-d470-47e9-a741-d381c2b2cb6f", "name": "Jane Doe's Checking" } ... HTTP/1.1 201 Created Location: https://api-sandbox.dwolla.com/funding-sources/375c6781-2a17-476c-84f7-db7d2f6ffb31 ``` Once you've received a successful response from the Dwolla API, you'll use the unique funding source URL to identify the Customer's bank when [initiating ACH](https://docs.dwolla.com/#initiate-a-transfer?utm_campaign=Plaid-Documentation&utm_source=Plaid&utm_medium=Referral) or [RTP transfers](https://developers.dwolla.com/concepts/real-time-payments#real-time-payments?utm_campaign=Plaid-Documentation&utm_source=Landing-Page&utm_medium=Referral) . ##### Testing your Dwolla integration  You can create Dwolla `processor_tokens` in Sandbox (sandbox.plaid.com, allows testing with simulated users) or Production (production.plaid.com, requires Dwolla Production credentials). To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) when launching Link with a `link_token` created in the Sandbox environment. When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`. ##### Get ready for production  Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ). To move to Production, please request access from the [Dashboard](https://dashboard.plaid.com/developers/keys) . #### Example code in Plaid Pattern  For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135) . For a tutorial walkthrough of creating a similar app with Dwolla support, see [Account funding tutorial](https://github.com/plaid/account-funding-tutorial) . #### Support and questions  Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) . If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can. --- # Auth | Plaid Docs Add Gainbridge to your app  =========================== #### Instantly authenticate your customers' bank accounts to fund policies through Gainbridge's Bank Accounts API  (An image of "Partnership Gainbridge logo") #### Overview  Plaid and Gainbridge have partnered together to integrate Plaid's connectivity platform with Gainbridge's digital investing platform. This integration will allow you to securely establish and verify your users' bank accounts through Plaid, and safely transmit authenticated account information to Gainbridge for policy funding through ACH payments: * Instantly authenticate users' bank accounts with Plaid Link (i.e. enhance user experience, reduce wait times for bank account verification with Microdeposits). * Securely share tokenized banking data to connect with Gainbridge's Bank Accounts API, used to initiate ACH debits on your customer's bank accounts to fund a Gainbridge policy. #### Getting Started  You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/plaid-link/) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified [Gainbridge account](https://enterprise.gainbridge.io/contact) to add a bank funding source. Your customers will use Link to authenticate with their financial institution and select the bank account they wish to connect. From there, you'll receive a Plaid `access_token` and a Gainbridge `processor_token`, which allows you to quickly and securely verify a bank funding source via [Gainbridge's API](https://enterprise.gainbridge.io/platform-overview) without having to store any sensitive banking information. Utilizing Plaid + Gainbridge enables a seamless workflow for connecting external financial accounts to Gainbridge. #### Instructions  ##### Set up your accounts  You'll need accounts at both Plaid and Gainbridge in order to use the Plaid + Gainbridge integration. You'll also need to enable your Plaid account for the Gainbridge integration. First, you will need to work with the Gainbridge team to [sign up for a Gainbridge account](https://enterprise.gainbridge.io/contact) , if you do not already have one. Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup) . To enable your Plaid account for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Gainbridge to enable the integration. You'll need to complete your Plaid [Application Profile](https://dashboard.plaid.com/settings/company/app-branding) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks. Finally, you'll need to go to the [Link customization UI](https://dashboard.plaid.com/link/data-transparency-v5) and pick the use cases that you will be using Gainbridge to power, so that Plaid can request the appropriate authorization and consent from your end users. If you have any questions, contact Gainbridge. ##### Create a link\_token  In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. For a full list of `link_token` configurations, see [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) . ```node const request: LinkTokenCreateRequest = { loading_sample: true }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```python request = LinkTokenCreateRequest( loading_sample=True ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "loading_sample": true }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { loading_sample: true } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .loadingSample(true); Response response = client .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```go request := plaid.NewLinkTokenCreateRequest( "Sample App App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetLoadingSample(true) linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := linkTokenCreateResp.GetLinkToken(); ``` ##### Integrate with Plaid Link  Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Gainbridge `processor_token`. Integrate Link ```javascript ``` See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations. `Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe. ##### Write server-side handler  The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint. The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Gainbridge, set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one account. Once you have identified the account you will use, you will send the `access_token` and `account_id` property of the account to Plaid via the [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) endpoint in order to create a Gainbridge `processor_token`. You'll send this token to Gainbridge and they will use it to securely retrieve account details from Plaid. You can create Gainbridge `processor_tokens` in both API environments: * Sandbox ([https://sandbox.plaid.com](https://sandbox.plaid.com) ): test simulated users * Production ([https://production.plaid.com](https://production.plaid.com) ): production environment for when you're ready to go live and have valid Gainbridge Production credentials ```node const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest, } = require('plaid'); // Change sandbox to production when you're ready to go live! const configuration = new Configuration({ basePath: PlaidEnvironments[process.env.PLAID_ENV], baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, 'Plaid-Version': '2020-09-14', }, }, }); const plaidClient = new PlaidApi(configuration); try { // Exchange the public_token from Plaid Link for an access token. const tokenResponse = await plaidClient.itemPublicTokenExchange({ public_token: publicToken, }); const accessToken = tokenResponse.data.access_token; // Create a processor token for a specific account id. const request: ProcessorTokenCreateRequest = { access_token: accessToken, account_id: accountID, processor: 'gainbridge', }; const processorTokenResponse = await plaidClient.processorTokenCreate( request, ); const processorToken = processorTokenResponse.data.processor_token; } catch (error) { // handle error } ``` ```bash # Exchange token curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "${PUBLIC_TOKEN}" }' # Create a processor token for a specific account id. curl -X POST https://sandbox.plaid.com/processor/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}", "account_id": "${ACCOUNT_ID}", "processor": "gainbridge" }' ``` ```ruby require 'plaid' # Change sandbox to production when you're ready to go live! configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] configuration.api_key['Plaid-Version'] = '2020-09-14' api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) # Exchange the public token from Plaid Link for an access token. item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: public_token } ) exchange_token_response = client.item_public_token_exchange(item_public_token_exchange_request) access_token = exchange_token_response.access_token # Create a processor token for a specific account id. processor_token_create_request = Plaid::ProcessorTokenCreateRequest.new( { access_token: access_token, account_id: account_id, processor: "gainbridge" } ) create_response = client.processor_token_create(processor_token_create_request) processor_token = create_response.processor_token ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; import com.plaid.client.model.ProcessorTokenCreateRequest; import com.plaid.client.model.ProcessorTokenCreateResponse; // Change sandbox to production when you're ready to go live! HashMap apiKeys = new HashMap(); apiKeys.put("clientId", plaidClientId); apiKeys.put("secret", plaidSecret); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange the public token from Plaid Link for an access token. ItemPublicTokenExchangeRequest exchangeRequest = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response exchangeResponse = client() .itemPublicTokenExchange(exchangeRequest) .execute(); // Create a processor token for a specific account id. if (exchangeResponse.isSuccessful()) { String accessToken = exchangeResponse.body().getAccessToken(); ProcessorTokenCreateRequest createRequest = new ProcessorTokenCreateRequest() .accessToken(accessToken) .processor("gainbridge") .accountId("FooBarAccountId"); Response createResponse = client() .processorTokenCreate(createRequest) .execute(); if (createResponse.isSuccessful()) { String processorToken = createResponse.body().getProcessorToken(); } } ``` ```python import plaid from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest from plaid.model.processor_token_create_request import ProcessorTokenCreateRequest # Change sandbox to production when you're ready to go live! configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, 'plaidVersion': '2020-09-14' } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Exchange the public token from Plaid Link for an access token. exchange_request = ItemPublicTokenExchangeRequest(public_token=public_token) exchange_token_response = client.item_public_token_exchange(exchange_request) access_token = exchange_token_response['access_token'] # Create a processor token for a specific account id. create_request = ProcessorTokenCreateRequest( access_token=access_token, account_id=account_id, processor="gainbridge" ) create_response = client.processor_token_create(create_request) processor_token = create_response['processor_token'] ``` ```go import ( "context" "os" plaid "github.com/plaid/v3/plaid-go" ) // create the client configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) // exchange the public_token for an access_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest("PUBLIC_TOKEN"), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() // get the account id accountsResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest(plaid.AccountsGetRequest{ AccessToken: accessToken, }).Execute() accountID := accountsResp.GetAccounts()[0].GetAccountId() // create a processor token for the specific account id request := plaid.NewProcessorTokenCreateRequest(accessToken, accountID, "gainbridge") stripeTokenResp, _, err := client.PlaidApi.ProcessorTokenCreate(ctx).ProcessorTokenCreateRequest( *request, ).Execute() ``` For a valid request, the API will return a JSON response similar to: Processor token create response ```json { "processor_token": "processor-sandbox-0asd1-a92nc", "request_id": "m8MDnv9okwxFNBV" } ``` For possible error codes, see the full listing of Plaid [error codes](https://plaid.com/docs/errors/index.html.md) . #### Example code in Plaid Pattern  For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135) #### Launching to Production  ##### Test with Sandbox credentials  To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) along when launching Link with a `link_token` created in the Sandbox environment. When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`. ##### Get ready for production  Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ). To move to Production, please request access from the [Dashboard](https://dashboard.plaid.com/developers/keys) . You will need Gainbridge Production credentials prior to initiating live traffic in the Gainbridge API with Plaid. ##### Support and questions  Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) . If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can. --- # Auth - Gusto | Plaid Docs Add Gusto to your app  ====================== #### Build payroll with Gusto, then use Plaid Auth to instantly connect your customers' bank accounts and run payroll faster  (An image of "Partnership Gusto logo") #### Overview  Gusto and Plaid have partnered so your customers can quickly and easily configure company bank accounts for seamless, in-app payroll. You shouldn't compromise on payroll accuracy and compliance for your customers and their employees. With Gusto Embedded Payroll's APIs, you can leverage the road-tested payroll engine and expertise of Gusto to build payroll capabilities directly into your platform. This integration allows your customers to easily connect company bank accounts through Plaid's Auth flow. A `processor_token` is a Plaid token used by Gusto to make API calls on your behalf. You will generate a `processor_token` on behalf of the customer and then pass that token to Gusto. The token allows Gusto to instantly retrieve bank account details, so you don't need to store and protect sensitive bank information. #### Getting Started  You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/plaid-link/) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified [Gusto account](https://dev.gusto.com/accounts/sign_up) to add a bank funding source. Your customers will use Link to authenticate with their financial institution and select the bank account they wish to connect. From there, you'll receive a Plaid `access_token` and a Gusto `processor_token`, which allows you to quickly and securely verify a bank funding source via [Gusto's API](https://docs.gusto.com) without having to store any sensitive banking information. Utilizing Plaid + Gusto enables a seamless workflow for connecting external financial accounts to Gusto. #### Instructions  ##### Set up your accounts  You'll need accounts at both Plaid and Gusto in order to use the Plaid + Gusto integration. You'll also need to enable your Plaid account for the Gusto integration. First, you will need to work with the Gusto team to [sign up for a Gusto account](https://dev.gusto.com/accounts/sign_up) , if you do not already have one. Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup) . To enable your Plaid account for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Gusto to enable the integration. You'll need to complete your Plaid [Application Profile](https://dashboard.plaid.com/settings/company/app-branding) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks. Finally, you'll need to go to the [Link customization UI](https://dashboard.plaid.com/link/data-transparency-v5) and pick the use cases that you will be using Gusto to power, so that Plaid can request the appropriate authorization and consent from your end users. If you have any questions, contact Gusto. ##### Create a link\_token  In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. For a full list of `link_token` configurations, see [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) . ```node const request: LinkTokenCreateRequest = { loading_sample: true }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```python request = LinkTokenCreateRequest( loading_sample=True ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "loading_sample": true }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { loading_sample: true } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .loadingSample(true); Response response = client .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```go request := plaid.NewLinkTokenCreateRequest( "Sample App App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetLoadingSample(true) linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := linkTokenCreateResp.GetLinkToken(); ``` ##### Integrate with Plaid Link  Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Gusto `processor_token`. Integrate Link ```javascript ``` See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations. `Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe. ##### Write server-side handler  The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint. The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Gusto, set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one account. Once you have identified the account you will use, you will send the `access_token` and `account_id` property of the account to Plaid via the [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) endpoint in order to create a Gusto `processor_token`. You'll send this token to Gusto and they will use it to securely retrieve account details from Plaid. You can create Gusto `processor_tokens` in both API environments: * Sandbox ([https://sandbox.plaid.com](https://sandbox.plaid.com) ): test simulated users * Production ([https://production.plaid.com](https://production.plaid.com) ): production environment for when you're ready to go live and have valid Gusto Production credentials ```node const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest, } = require('plaid'); // Change sandbox to production when you're ready to go live! const configuration = new Configuration({ basePath: PlaidEnvironments[process.env.PLAID_ENV], baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, 'Plaid-Version': '2020-09-14', }, }, }); const plaidClient = new PlaidApi(configuration); try { // Exchange the public_token from Plaid Link for an access token. const tokenResponse = await plaidClient.itemPublicTokenExchange({ public_token: publicToken, }); const accessToken = tokenResponse.data.access_token; // Create a processor token for a specific account id. const request: ProcessorTokenCreateRequest = { access_token: accessToken, account_id: accountID, processor: 'gusto', }; const processorTokenResponse = await plaidClient.processorTokenCreate( request, ); const processorToken = processorTokenResponse.data.processor_token; } catch (error) { // handle error } ``` ```bash # Exchange token curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "${PUBLIC_TOKEN}" }' # Create a processor token for a specific account id. curl -X POST https://sandbox.plaid.com/processor/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}", "account_id": "${ACCOUNT_ID}", "processor": "gusto" }' ``` ```ruby require 'plaid' # Change sandbox to production when you're ready to go live! configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] configuration.api_key['Plaid-Version'] = '2020-09-14' api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) # Exchange the public token from Plaid Link for an access token. item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: public_token } ) exchange_token_response = client.item_public_token_exchange(item_public_token_exchange_request) access_token = exchange_token_response.access_token # Create a processor token for a specific account id. processor_token_create_request = Plaid::ProcessorTokenCreateRequest.new( { access_token: access_token, account_id: account_id, processor: "gusto" } ) create_response = client.processor_token_create(processor_token_create_request) processor_token = create_response.processor_token ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; import com.plaid.client.model.ProcessorTokenCreateRequest; import com.plaid.client.model.ProcessorTokenCreateResponse; // Change sandbox to production when you're ready to go live! HashMap apiKeys = new HashMap(); apiKeys.put("clientId", plaidClientId); apiKeys.put("secret", plaidSecret); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange the public token from Plaid Link for an access token. ItemPublicTokenExchangeRequest exchangeRequest = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response exchangeResponse = client() .itemPublicTokenExchange(exchangeRequest) .execute(); // Create a processor token for a specific account id. if (exchangeResponse.isSuccessful()) { String accessToken = exchangeResponse.body().getAccessToken(); ProcessorTokenCreateRequest createRequest = new ProcessorTokenCreateRequest() .accessToken(accessToken) .processor("gusto") .accountId("FooBarAccountId"); Response createResponse = client() .processorTokenCreate(createRequest) .execute(); if (createResponse.isSuccessful()) { String processorToken = createResponse.body().getProcessorToken(); } } ``` ```python import plaid from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest from plaid.model.processor_token_create_request import ProcessorTokenCreateRequest # Change sandbox to production when you're ready to go live! configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, 'plaidVersion': '2020-09-14' } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Exchange the public token from Plaid Link for an access token. exchange_request = ItemPublicTokenExchangeRequest(public_token=public_token) exchange_token_response = client.item_public_token_exchange(exchange_request) access_token = exchange_token_response['access_token'] # Create a processor token for a specific account id. create_request = ProcessorTokenCreateRequest( access_token=access_token, account_id=account_id, processor="gusto" ) create_response = client.processor_token_create(create_request) processor_token = create_response['processor_token'] ``` ```go import ( "context" "os" plaid "github.com/plaid/v3/plaid-go" ) // create the client configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) // exchange the public_token for an access_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest("PUBLIC_TOKEN"), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() // get the account id accountsResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest(plaid.AccountsGetRequest{ AccessToken: accessToken, }).Execute() accountID := accountsResp.GetAccounts()[0].GetAccountId() // create a processor token for the specific account id request := plaid.NewProcessorTokenCreateRequest(accessToken, accountID, "gusto") stripeTokenResp, _, err := client.PlaidApi.ProcessorTokenCreate(ctx).ProcessorTokenCreateRequest( *request, ).Execute() ``` For a valid request, the API will return a JSON response similar to: Processor token create response ```json { "processor_token": "processor-sandbox-0asd1-a92nc", "request_id": "m8MDnv9okwxFNBV" } ``` For possible error codes, see the full listing of Plaid [error codes](https://plaid.com/docs/errors/index.html.md) . #### Example code in Plaid Pattern  For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135) #### Launching to Production  ##### Test with Sandbox credentials  To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) along when launching Link with a `link_token` created in the Sandbox environment. When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`. ##### Get ready for production  Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ). To move to Production, please request access from the [Dashboard](https://dashboard.plaid.com/developers/keys) . You will need Gusto Production credentials prior to initiating live traffic in the Gusto API with Plaid. ##### Support and questions  Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) . If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can. --- # Auth - Money movement partnerships | Plaid Docs Auth Payment Partners  ====================== #### Find payment providers who have partnered with Plaid to provide general purpose ACH money movement  #### Overview  Many Plaid developers choose to use a Plaid partner to move money with Auth. You will use Plaid Link initialized with the Auth product, but instead of using Plaid Auth endpoints, you will use endpoints from the payment platform, giving you access to payment functionality while freeing you from having to securely store sensitive bank account information. The table below contains a list of partners and a set of customized instructions for integrating with each partner. ##### Global payments options  Money movement via Plaid partners is only available for financial institutions within the US (with multiple providers below) and Canada (with [VoPay](https://plaid.com/docs/auth/partnerships/vopay/index.html.md) , [Modern Treasury](https://plaid.com/docs/auth/partnerships/modern-treasury/index.html.md) , or [Finix](https://plaid.com/docs/auth/partnerships/finix/index.html.md) ). In Europe, [Payment Initiation](https://plaid.com/docs/payment-initiation/index.html.md) provides an easy and secure way to transfer funds. | Partner | Description | | --- | --- | | [Dwolla](https://plaid.com/docs/auth/partnerships/dwolla/index.html.md) | Instantly authenticate your customers' bank accounts for use with Dwolla's ACH API | | [Square](https://plaid.com/docs/auth/partnerships/square/index.html.md) | Instantly authenticate your customers' bank accounts for use with the Square Web Payments SDK | | [ACHQ](https://plaid.com/docs/auth/partnerships/achq/index.html.md) | Instantly authenticate your customers' bank accounts for use with ACHQ's ACH API | | [Roll by ADP](https://plaid.com/docs/auth/partnerships/adp-roll/index.html.md) | Authenticate your customers' bank accounts for secure payroll direct deposit support. | | [Adyen](https://plaid.com/docs/auth/partnerships/adyen/index.html.md) | Validate bank accounts and reduce returns through an end-to-end pay-with-your-bank solution with Adyen | | [Alpaca](https://plaid.com/docs/auth/partnerships/alpaca/index.html.md) | Use Alpaca with Plaid Auth to send and receive payments | | [Ansa](https://plaid.com/docs/auth/partnerships/ansa/index.html.md) | Instantly authenticate your customers' bank accounts for use with the Ansa API to enable wallet funding over ACH | | [Apex Fintech Solutions](https://plaid.com/docs/auth/partnerships/apex-clearing/index.html.md) | Instantly authenticate your investors' bank accounts for use with Apex Fintech Solutions Cash API | | [Astra](https://plaid.com/docs/auth/partnerships/astra/index.html.md) | Instantly authenticate your customer's bank accounts for automated ACH transfers through the Astra platform | | [Atomic](https://plaid.com/docs/auth/partnerships/atomic/index.html.md) | Instantly authenticate your customers' bank accounts to seamlessly fund investment accounts | | [Bakkt](https://plaid.com/docs/auth/partnerships/bakkt/index.html.md) | Instantly authenticate your customer's accounts to use with Bakkt Fiat Services API for ACH based money movement | | [Bond](https://plaid.com/docs/auth/partnerships/bond/index.html.md) | Instantly authenticate your customers' bank accounts for use with Bond's ACH Transfers API | | [Check](https://plaid.com/docs/auth/partnerships/check/index.html.md) | Check lets you embed payroll in your product and easily configure and authenticate direct deposit payments | | [Checkbook](https://plaid.com/docs/auth/partnerships/checkbook/index.html.md) | Instantly authenticate your customers' bank accounts for use with Checkbook's payment solution -- including ACH, real-time payments, push to card, virtual cards, and checks | | [Checkout.com](https://plaid.com/docs/auth/partnerships/checkout/index.html.md) | Instantly authenticate bank account details for use with Checkout.com's Unified Payments API, and unlock unrivaled payment performance | | [DriveWealth](https://plaid.com/docs/auth/partnerships/drivewealth/index.html.md) | Enable your customers to instantly and securely fund DriveWealth supported investment accounts by linking their bank account with Plaid | | [Finix](https://plaid.com/docs/auth/partnerships/finix/index.html.md) | Instantly add customer bank accounts to Finix to accept and send payments with tokenized payment information. It's fast, frictionless, and secure. | | [Fortress Trust](https://plaid.com/docs/auth/partnerships/fortress-trust/index.html.md) | Instantly allow end customers to connect, verify and authorize funding to their Fortress Trust account from their external bank accounts | | [Gainbridge](https://plaid.com/docs/auth/partnerships/gainbridge/index.html.md) | Instantly authenticate your customers' bank accounts to fund policies through Gainbridge's Bank Accounts API | | [Galileo](https://plaid.com/docs/auth/partnerships/galileo/index.html.md) | Instantly authenticate your customers' bank accounts for account opening and funding | | [Gusto](https://plaid.com/docs/auth/partnerships/gusto/index.html.md) | Build payroll with Gusto, then use Plaid Auth to instantly connect your customers' bank accounts and run payroll faster | | [Highnote](https://plaid.com/docs/auth/partnerships/highnote/index.html.md) | Instantly authenticate your customer's bank accounts for use with the Highnote Platform to store account details, transfer funds, and make payments | | [Lithic](https://plaid.com/docs/auth/partnerships/lithic/index.html.md) | Instant bank authentication for ACH payments and card loads | | [Marqeta](https://plaid.com/docs/auth/partnerships/marqeta/index.html.md) | Integrate Plaid and Marqeta's APIs to seamlessly authenticate your customer's bank account prior to an ACH transfer | | [Modern Treasury](https://plaid.com/docs/auth/partnerships/modern-treasury/index.html.md) | Instantly authenticate your customers' bank accounts for use with Modern Treasury's ACH API | | [Moov](https://plaid.com/docs/auth/partnerships/moov/index.html.md) | Instantly authenticate your customers' bank accounts to enable them to accept, store, and disburse funds with Moov | | [Open Ledger](https://plaid.com/docs/auth/partnerships/open-ledger/index.html.md) | Connect your customer's bank account to Open Ledger's embedded accounting API | | [Paynote](https://plaid.com/docs/auth/partnerships/paynote/index.html.md) | Enhance your checkout and reduce returns with Paynote ACH. Utilize Plaid's verification and real-time balance checks to instantly debit and credit bank accounts. | | [Riskified](https://plaid.com/docs/auth/partnerships/riskified/index.html.md) | Provide fraud screening and ACH payment guarantee | | [Rize](https://plaid.com/docs/auth/partnerships/rize/index.html.md) | Use Plaid to instantly verify and connect your customers' external bank accounts for use within the Rize Platform | | [Sardine](https://plaid.com/docs/auth/partnerships/sardine/index.html.md) | Protect your users by using Sardine's all-in-one fraud and compliance API | | [ScribeUp](https://plaid.com/docs/auth/partnerships/scribeup/index.html.md) | Embed subscription management into your digital banking experience | | [Sila Money](https://plaid.com/docs/auth/partnerships/sila-money/index.html.md) | Banking, Digital Wallets, and ACH Payments API for software teams | | [Silicon Valley Bank](https://plaid.com/docs/auth/partnerships/svb/index.html.md) | Instantly authenticate your customers' bank accounts for use with Silicon Valley Bank's ACH API | | [Solid](https://plaid.com/docs/auth/partnerships/solid/index.html.md) | Instantly authenticate external bank accounts for use with the Solid Platform | | [Stake](https://plaid.com/docs/auth/partnerships/stake/index.html.md) | Instantly authenticate your resident bank accounts for use with the Stake Enterprise API. | | [Straddle](https://plaid.com/docs/auth/partnerships/straddle/index.html.md) | Integrate Plaid with Straddle to deliver secure, identity-linked bank payments that settle quickly and feel as simple and reliable as using a debit card. | | [Stripe](https://plaid.com/docs/auth/partnerships/stripe/index.html.md) | Instantly authenticate your customers' bank accounts for use with Stripe's ACH API | | [TabaPay](https://plaid.com/docs/auth/partnerships/taba-pay/index.html.md) | Instantly process ACH/RTP/FedNow with TabaPay's Unified API using your Plaid Token | | [Treasury Prime](https://plaid.com/docs/auth/partnerships/treasury-prime/index.html.md) | Send payments and create counterparties with the Treasury Prime API | | [Unit](https://plaid.com/docs/auth/partnerships/unit/index.html.md) | Instantly authenticate counterparties' bank accounts for use with the Unit API | | [VoPay](https://plaid.com/docs/auth/partnerships/vopay/index.html.md) | Eliminate inefficiencies of US and Canadian online bank account payments with VoPay's EFT / ACH and Plaid | | [Wedbush](https://plaid.com/docs/auth/partnerships/wedbush/index.html.md) | Plaid-linked bank accounts can be connected to fund or withdraw from accounts on the Wedbush Securities platform. | | [Zero Hash](https://plaid.com/docs/auth/partnerships/zero-hash/index.html.md) | Use Zero Hash with Plaid Auth to embed bank account linking for ACH-funded crypto trades | For more information, see the full list of partners in the [Plaid Dashboard](https://dashboard.plaid.com/developers/integrations) . #### Example code in Plaid Pattern  For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135) . --- # Auth - Stripe | Plaid Docs Add Stripe to your app  ======================= #### Use Stripe with Plaid Auth to send and receive payments  (An image of "Plaid + Stripe logo image") Plaid and Stripe have partnered to offer frictionless money transfers without the need to ever handle an account or routing number. Use [Plaid Link](https://plaid.com/docs/link/index.html.md) to instantly authenticate your customer's account and generate a Stripe [bank account token](https://stripe.com/docs/api#create_bank_account_token) so that you can accept ACH payments via Stripe. This guide is designed for those who already have developer accounts with both Stripe and Plaid. If that's not you, [Sign up for a Plaid Dashboard account](https://dashboard.plaid.com/signup) , then head over to the [Stripe docs](https://dashboard.stripe.com/register) to get a Stripe account. This guide describes integrating Plaid with the [Stripe Payment Intents API](https://docs.stripe.com/payments/payment-intents) , which is the modern way to send and receive ACH payments via Stripe. Existing customers who have integrations using the older Stripe Charges and Sources API should contact their Plaid account manager with any questions. For more details on the deprecation of the Charges and Sources API, see the [changelog](https://plaid.com/docs/changelog/index.html.md#february-20-2026) . #### Getting Started  You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/docs/link/index.html.md) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. Your customers will use Link to authenticate with their financial institution and select the depository account they wish to use for ACH transactions. From there, you'll receive a Plaid `access_token`, allowing you to leverage real-time balance checks and transaction data, and a Stripe `bank_account_token`, which allows you to move money via Stripe's ACH API without ever handling an account or routing number. #### Instructions  ##### Set up your Plaid and Stripe accounts  You'll need accounts at both Plaid and Stripe in order to use the Plaid Link + Stripe integration. You'll also need to connect your Plaid and Stripe accounts so that Plaid can facilitate the creation of bank account tokens on your behalf. First, [sign up for a Stripe account](https://dashboard.stripe.com/register) if you do not already have one, and then verify that it is enabled for ACH access. To verify that your Stripe account is ACH enabled, head to the Settings → Payment Methods section of the Stripe Dashboard and make sure that ACH Direct Debit is marked as enabled. If it is not, click the button to enable it. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup/stripe) . To verify that your Plaid account is enabled for the Stripe integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If you see: (An image of "Unlinked Stripe account") your Plaid account is enabled for the integration but you have not connected your Stripe account. Click the 'Connect With Stripe' button to connect your Plaid and Stripe accounts. This step is required so that Plaid can facilitate the creation of Stripe bank account tokens on your behalf. Once your Stripe account is connected, you'll see: (An image of "linked Stripe account") Your Plaid account is now set up for the integration! ###### Contact Stripe to enable the Payment Intents API for Plaid  To use Plaid with the Stripe Payment Intents API, you will need to be manually enabled by Stripe. The following is a template you can use to request access: Email template to request Plaid / Stripe enablement ```switcher To: plaid-referral@stripe.com Cc: partnerships@plaid.com Subject: {{Your business name}} is requesting Plaid <> Stripe Payment Intents support Stripe Account ID: {{your Stripe account id, beginning with acct_}} Use Case: {{A description of what you are trying to accomplish with your Stripe + Plaid integration.}} Thank you for your assistance, {{Your name}} ``` ##### Complete your Plaid application profile and company profile  After connecting your Stripe and Plaid accounts, you'll need to complete your Plaid [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks. ##### Create a link\_token  In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. For a full list of parameters, see the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) reference. To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) . ```node app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['auth'], language: 'en', webhook: 'https://webhook.example.com', redirect_uri: 'https://domainname.com/oauth-page.html', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "products": ["auth"], "country_codes": ["US"], "language": "en", "webhook": "https://webhook.example.com", "redirect_uri": "https://domainname.com/oauth-page.html" }' ``` ```ruby post '/api/create_link_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: client_user_id }, client_name: 'Plaid Test App', products: ['auth'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.example.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.Products; import com.plaid.client.model.CountryCode; import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; public class PlaidExample { ... static class GetLinkToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.fromValue("auth"))) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .redirectUri("https://domainname.com/oauth-page.html") .webhook("https://webhook.example.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.link_token_create_request import LinkTokenCreateRequest from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser from plaid.model.products import Products from plaid.model.country_code import CountryCode @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( products=[Products("auth")], client_name="Plaid Test App", country_codes=[CountryCode('US')], redirect_uri='https://domainname.com/oauth-page.html', language='en', webhook='https://webhook.example.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetRedirectUri("https://domainname.com/oauth-page.html") request.SetProducts([]plaid.Products{plaid.PRODUCTS_AUTH}) resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` ##### Integrate with Plaid Link  Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Stripe bank account token. Integrate Link ```javascript ``` See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations. `Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe. ##### Write server-side handler  The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint. The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. In order to avoid any confusion about which account your user wishes to use with Stripe, it is recommended to set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one element. Once you have identified the account you will use, you will call [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) , sending Plaid the `account_id` property of the account along with the `access_token` you obtained from [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . Plaid will create and return a Stripe [bank account token](https://stripe.com/docs/api#create_bank_account_token) for this account, which can then be used to move money via Stripe's ACH API. The bank account token will be linked to the Stripe account you linked in your [Plaid Dashboard](https://dashboard.plaid.com/) . Note that the Stripe bank account token is a one-time use token. To store bank account information for later use, you can use a Stripe [customer object](https://stripe.com/docs/api/customers/object) and create an associated [bank account](https://stripe.com/docs/api/customer_bank_accounts/create) from the token, or you can use a Stripe [Custom account](https://stripe.com/docs/api/accounts) and create an associated [external bank account](https://stripe.com/docs/api/external_account_bank_accounts/create) from the token. This bank account information should work indefinitely, unless the user's bank account information changes or they revoke Plaid's permissions to access their account (when using certain financial institutions). The Plaid `access_token`, on the other hand, does not expire and should be persisted securely. Stripe bank account information cannot be modified once the bank account token has been created. If you ever need to change the bank account details used by Stripe for a specific customer, you should repeat this process from the beginning, including creating a `link_token`, sending the customer through the Link flow, generating a new bank account token, and creating a new customer object or Custom account. ```node // Change sandbox to production when you're ready to go live! const { Configuration, PlaidApi, PlaidEnvironments, ProcessorStripeBankAccountTokenCreateRequest, } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments[process.env.PLAID_ENV], baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, 'Plaid-Version': '2020-09-14', }, }, }); const plaidClient = new PlaidApi(configuration); try { // Exchange the public_token from Plaid Link for an access token. const tokenResponse = await plaidClient.itemPublicTokenExchange({ public_token: publicToken, }); const accessToken = tokenResponse.data.access_token; // Generate a bank account token const request: ProcessorStripeBankAccountTokenCreateRequest = { access_token: accessToken, account_id: accountID, }; const stripeTokenResponse = await plaidClient.processorStripeBankAccountTokenCreate( request, ); const bankAccountToken = stripeTokenResponse.data.stripe_bank_account_token; } catch (error) { // handle error } ``` ```bash # Exchange token curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "${PUBLIC_TOKEN}" }' # Create bank account token curl -X POST https://sandbox.plaid.com/processor/stripe/bank_account_token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}", "account_id": "${ACCOUNT_ID}" }' ``` ```ruby require 'plaid' # Change sandbox to production when you're ready to go live! configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] configuration.api_key['Plaid-Version'] = '2020-09-14' api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new item_public_token_exchange_request.public_token = public_token exchange_token_response = client.item_public_token_exchange( item_public_token_exchange_request ) access_token = exchange_token_response.access_token processor_token_create_request = Plaid::ProcessorStripeBankAccountTokenCreateRequest.new processor_token_create_request.access_token = access_token processor_token_create_request.account_id = account_id stripe_response = client.processor_stripe_bank_account_token_create(processor_token_create_request) bank_account_token = stripe_response.stripe_bank_account_token ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; import com.plaid.client.model.ProcessorStripeBankAccountTokenCreateRequest; import com.plaid.client.model.ProcessorStripeBankAccountTokenCreateResponse; // Change sandbox to production when you're ready to go live! HashMap apiKeys = new HashMap(); apiKeys.put("clientId", plaidClientId); apiKeys.put("secret", plaidSecret); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange the public token from Plaid Link for an access token. ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response exchangeResponse = client() .itemPublicTokenExchange(request) .execute(); if (exchangeResponse.isSuccessful()) { String accessToken = exchangeResponse.body().getAccessToken(); ProcessorStripeBankAccountTokenCreateRequest processorTokenRequest = new ProcessorStripeBankAccountTokenCreateRequest() .accessToken(accessToken) .accountId("FooBarAccountId"); Response stripeResponse = client() .processorStripeBankAccountTokenCreate(processorTokenRequest) .execute(); if (stripeResponse.isSuccessful()) { String bankAccountToken = stripeResponse.body().getStripeBankAccountToken(); } } ``` ```python import plaid from plaid.api import plaid_api from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest from plaid.model.processor_stripe_bank_account_token_create_request import ProcessorStripeBankAccountTokenCreateRequest # Change sandbox to production when you're ready to go live! configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, 'plaidVersion': '2020-09-14' } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) exchange_request = ItemPublicTokenExchangeRequest(public_token=public_token) exchange_token_response = client.item_public_token_exchange(exchange_request) access_token = exchange_token_response['access_token'] request = ProcessorStripeBankAccountTokenCreateRequest( access_token=access_token, account_id=account_id, ) stripe_response = client.processor_stripe_bank_account_token_create(request) bank_account_token = stripe_response['stripe_bank_account_token'] ``` ```go import ( "context" "os" plaid "github.com/plaid/plaid-go/v40/plaid" ) // create the client configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) // exchange the public_token for an access_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest("PUBLIC_TOKEN"), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() // get the account id accountsResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest(plaid.AccountsGetRequest{ AccessToken: accessToken, }).Execute() accountID := accountsResp.GetAccounts()[0].GetAccountId() // create a stripe token for the specific account id request := plaid.NewProcessorStripeBankAccountTokenCreateRequest(accessToken, accountID) stripeTokenResp, _, err := client.PlaidApi.ProcessorStripeBankAccountTokenCreate(ctx).ProcessorStripeBankAccountTokenCreateRequest( *request, ).Execute() ``` For a valid request, the API will return a JSON response similar to: ```json { "stripe_bank_account_token": "btok_5oEetfLzPklE1fwJZ7SG", "request_id": "[Unique request ID]" } ``` For possible error codes, see the full listing of Plaid [error codes](https://plaid.com/docs/errors/index.html.md) . Note: The `account_id` parameter is required if you wish to receive a Stripe bank account token. ##### Test with Sandbox credentials  You can create Stripe bank account tokens in all three API environments: * Sandbox ([https://sandbox.plaid.com](https://sandbox.plaid.com) ): test simulated users with Stripe's "test mode" API * Production ([https://production.plaid.com](https://production.plaid.com) ): production environment for when you're ready to go live Plaid's Sandbox API environment is compatible with Stripe's "test mode" API. To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) when launching Link with a `link_token` created in the Sandbox environment. The Stripe bank account token created in the Sandbox environment will always match the Stripe bank test account with account number 000123456789 and routing number 110000000, and with the Stripe account that is linked in the Plaid Dashboard. Use Stripe's [ACH API](https://stripe.com/docs/guides/ach) in test mode to create test transfers using the bank account tokens you retrieve from Plaid's Sandbox API environment. Plaid's Sandbox is not compatible with the Stripe Sandbox environment. To test your Plaid - Stripe integration, you must use Stripe test mode, rather than Stripe Sandboxes. When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`. ##### Get ready for production  Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ), which allows you to test with Sandbox API credentials. To move to Production, request access from the [Dashboard](https://dashboard.plaid.com/settings/team/products) . ##### Next steps  Once you're successfully retrieving Stripe `bank_account_token`s, you're ready to make ACH transactions with Stripe. Head to [Stripe's ACH guide](https://stripe.com/docs/ach) to get started, and if you have any issues, please reach out to Stripe Support. If you are using the [Charges and Sources API](https://stripe.com/docs/ach-deprecated) , the Stripe documentation will walk you through the process. If you are using the Payment Intents API, you will first need to create a Stripe [customer](https://stripe.com/docs/api/customers/create#create_customer-payment_method) using the bank account token, then follow the [migration guide](https://stripe.com/docs/payments/ach-debit/migrations#create-payment-intent) to create a Payment Intent based on the bank account, using the [manual migration flow](https://docs.stripe.com/payments/ach-direct-debit/migrating-from-another-processor#manual-bank-account-migration) . Note that you will need to contact Stripe to request access to this flow. #### Example code in Plaid Pattern  For a real-life example of an app that integrates a processor partner, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. (Note that while the processor token creation call in Plaid Pattern's [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135) demonstrates usage of the [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) endpoint for creating a processor token, Stripe integrations should use the [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) endpoint instead and create a bank account token.) #### Troubleshooting  ##### Stripe bank account token not returned  When a `stripe_bank_account_token` is not returned, a typical cause is that your Stripe and Plaid accounts have not yet been linked. First, be sure that your Stripe account has been [configured to accept ACH transfers](https://stripe.com/docs/guides/ach) . Then, [link your Stripe account to your Plaid account](https://plaid.com/docs/auth/partnerships/stripe/index.html.md#set-up-your-plaid-and-stripe-accounts) and re-try your request. ##### Stripe::InvalidRequestError: No such token  The `Stripe::InvalidRequestError: No such token` error is returned by Stripe when the `bank_account_token` could not be used with the Stripe API. Make sure you are not mixing Plaid's Sandbox environment with Stripe's production environment and that, if you have more than one Stripe account or more than one Plaid `client_id`, you are using the Stripe account that is linked to the Plaid `client_id` you are using. #### Support and questions  Find answers to many common integration questions and concerns, such as pricing, sandbox and test mode usage in our [docs](https://plaid.com/docs/index.html.md) . If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can. --- # Auth - Wedbush | Plaid Docs Add Wedbush to your app  ======================== #### Plaid-linked bank accounts can be connected to fund or withdraw from accounts on the Wedbush Securities platform.  (An image of "Partnership Wedbush logo") #### Overview  Wedbush is a leading wealth management, brokerage and advisory firm, offering a complete suite of wealth management products and financial services. Plaid and Wedbush have partnered to offer a frictionless way to link investor's bank accounts and their brokerage accounts to facilitate seamless money movement. This integration is designed with security and privacy in mind, negating the need to share sensitive account details. #### Getting Started  You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/plaid-link/) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified [Wedbush account](https://portal.wedbushfutures.com/Login) to add a bank funding source. Your customers will use Link to authenticate with their financial institution and select the bank account they wish to connect. From there, you'll receive a Plaid `access_token` and a Wedbush `processor_token`, which allows you to quickly and securely verify a bank funding source via [Wedbush's API](https://www.wedbush.com/) without having to store any sensitive banking information. Utilizing Plaid + Wedbush enables a seamless workflow for connecting external financial accounts to Wedbush. #### Instructions  ##### Set up your accounts  You'll need accounts at both Plaid and Wedbush in order to use the Plaid + Wedbush integration. You'll also need to enable your Plaid account for the Wedbush integration. First, you will need to work with the Wedbush team to [sign up for a Wedbush account](https://portal.wedbushfutures.com/Login) , if you do not already have one. Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup) . To enable your Plaid account for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Wedbush to enable the integration. You'll need to complete your Plaid [Application Profile](https://dashboard.plaid.com/settings/company/app-branding) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks. Finally, you'll need to go to the [Link customization UI](https://dashboard.plaid.com/link/data-transparency-v5) and pick the use cases that you will be using Wedbush to power, so that Plaid can request the appropriate authorization and consent from your end users. If you have any questions, contact Wedbush. ##### Create a link\_token  In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. For a full list of `link_token` configurations, see [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) . ```node const request: LinkTokenCreateRequest = { loading_sample: true }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```python request = LinkTokenCreateRequest( loading_sample=True ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "loading_sample": true }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { loading_sample: true } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .loadingSample(true); Response response = client .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```go request := plaid.NewLinkTokenCreateRequest( "Sample App App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetLoadingSample(true) linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := linkTokenCreateResp.GetLinkToken(); ``` ##### Integrate with Plaid Link  Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Wedbush `processor_token`. Integrate Link ```javascript ``` See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations. `Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe. ##### Write server-side handler  The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint. The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Wedbush, set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one account. Once you have identified the account you will use, you will send the `access_token` and `account_id` property of the account to Plaid via the [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) endpoint in order to create a Wedbush `processor_token`. You'll send this token to Wedbush and they will use it to securely retrieve account details from Plaid. You can create Wedbush `processor_tokens` in both API environments: * Sandbox ([https://sandbox.plaid.com](https://sandbox.plaid.com) ): test simulated users * Production ([https://production.plaid.com](https://production.plaid.com) ): production environment for when you're ready to go live and have valid Wedbush Production credentials ```node const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest, } = require('plaid'); // Change sandbox to production when you're ready to go live! const configuration = new Configuration({ basePath: PlaidEnvironments[process.env.PLAID_ENV], baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, 'Plaid-Version': '2020-09-14', }, }, }); const plaidClient = new PlaidApi(configuration); try { // Exchange the public_token from Plaid Link for an access token. const tokenResponse = await plaidClient.itemPublicTokenExchange({ public_token: publicToken, }); const accessToken = tokenResponse.data.access_token; // Create a processor token for a specific account id. const request: ProcessorTokenCreateRequest = { access_token: accessToken, account_id: accountID, processor: 'wedbush', }; const processorTokenResponse = await plaidClient.processorTokenCreate( request, ); const processorToken = processorTokenResponse.data.processor_token; } catch (error) { // handle error } ``` ```bash # Exchange token curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "${PUBLIC_TOKEN}" }' # Create a processor token for a specific account id. curl -X POST https://sandbox.plaid.com/processor/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}", "account_id": "${ACCOUNT_ID}", "processor": "wedbush" }' ``` ```ruby require 'plaid' # Change sandbox to production when you're ready to go live! configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] configuration.api_key['Plaid-Version'] = '2020-09-14' api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) # Exchange the public token from Plaid Link for an access token. item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: public_token } ) exchange_token_response = client.item_public_token_exchange(item_public_token_exchange_request) access_token = exchange_token_response.access_token # Create a processor token for a specific account id. processor_token_create_request = Plaid::ProcessorTokenCreateRequest.new( { access_token: access_token, account_id: account_id, processor: "wedbush" } ) create_response = client.processor_token_create(processor_token_create_request) processor_token = create_response.processor_token ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; import com.plaid.client.model.ProcessorTokenCreateRequest; import com.plaid.client.model.ProcessorTokenCreateResponse; // Change sandbox to production when you're ready to go live! HashMap apiKeys = new HashMap(); apiKeys.put("clientId", plaidClientId); apiKeys.put("secret", plaidSecret); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange the public token from Plaid Link for an access token. ItemPublicTokenExchangeRequest exchangeRequest = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response exchangeResponse = client() .itemPublicTokenExchange(exchangeRequest) .execute(); // Create a processor token for a specific account id. if (exchangeResponse.isSuccessful()) { String accessToken = exchangeResponse.body().getAccessToken(); ProcessorTokenCreateRequest createRequest = new ProcessorTokenCreateRequest() .accessToken(accessToken) .processor("wedbush") .accountId("FooBarAccountId"); Response createResponse = client() .processorTokenCreate(createRequest) .execute(); if (createResponse.isSuccessful()) { String processorToken = createResponse.body().getProcessorToken(); } } ``` ```python import plaid from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest from plaid.model.processor_token_create_request import ProcessorTokenCreateRequest # Change sandbox to production when you're ready to go live! configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, 'plaidVersion': '2020-09-14' } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Exchange the public token from Plaid Link for an access token. exchange_request = ItemPublicTokenExchangeRequest(public_token=public_token) exchange_token_response = client.item_public_token_exchange(exchange_request) access_token = exchange_token_response['access_token'] # Create a processor token for a specific account id. create_request = ProcessorTokenCreateRequest( access_token=access_token, account_id=account_id, processor="wedbush" ) create_response = client.processor_token_create(create_request) processor_token = create_response['processor_token'] ``` ```go import ( "context" "os" plaid "github.com/plaid/v3/plaid-go" ) // create the client configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) // exchange the public_token for an access_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest("PUBLIC_TOKEN"), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() // get the account id accountsResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest(plaid.AccountsGetRequest{ AccessToken: accessToken, }).Execute() accountID := accountsResp.GetAccounts()[0].GetAccountId() // create a processor token for the specific account id request := plaid.NewProcessorTokenCreateRequest(accessToken, accountID, "wedbush") stripeTokenResp, _, err := client.PlaidApi.ProcessorTokenCreate(ctx).ProcessorTokenCreateRequest( *request, ).Execute() ``` For a valid request, the API will return a JSON response similar to: Processor token create response ```json { "processor_token": "processor-sandbox-0asd1-a92nc", "request_id": "m8MDnv9okwxFNBV" } ``` For possible error codes, see the full listing of Plaid [error codes](https://plaid.com/docs/errors/index.html.md) . #### Example code in Plaid Pattern  For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135) #### Launching to Production  ##### Test with Sandbox credentials  To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) along when launching Link with a `link_token` created in the Sandbox environment. When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`. ##### Get ready for production  Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ). To move to Production, please request access from the [Dashboard](https://dashboard.plaid.com/developers/keys) . You will need Wedbush Production credentials prior to initiating live traffic in the Wedbush API with Plaid. ##### Support and questions  Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) . If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can. --- # Auth - Zero Hash | Plaid Docs Add Zero Hash to your app  ========================== #### Use Zero Hash with Plaid Auth to embed bank account linking for ACH-funded crypto trades  (An image of "Partnership Zero Hash logo") #### Overview  Plaid and Zero Hash have partnered to enable end users to instantly connect their bank accounts to pre-fund a wallet or facilitate buy and sell crypto trades with ACH payments. Zero Hash's clients can use Plaid Link to instantly authenticate a user's financial account and generate a Plaid processor token to seamlessly and securely exchange user bank account information, without having to store any sensitive data. The processor token enables Zero Hash to initiate transaction requests directly from Plaid so that customers can execute ACH payments via Zero Hash's API. #### Getting Started  You'll first want to familiarize yourself with [Plaid Link](https://plaid.com/plaid-link/) , a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified [Zero Hash account](https://zerohash.com/contact/) to add a bank funding source. Your customers will use Link to authenticate with their financial institution and select the bank account they wish to connect. From there, you'll receive a Plaid `access_token` and a Zero Hash `processor_token`, which allows you to quickly and securely verify a bank funding source via [Zero Hash's API](https://docs.zerohash.com/web/) without having to store any sensitive banking information. Utilizing Plaid + Zero Hash enables a seamless workflow for connecting external financial accounts to Zero Hash. #### Instructions  ##### Set up your accounts  You'll need accounts at both Plaid and Zero Hash in order to use the Plaid + Zero Hash integration. You'll also need to enable your Plaid account for the Zero Hash integration. First, you will need to work with the Zero Hash team to [sign up for a Zero Hash account](https://zerohash.com/contact/) , if you do not already have one. Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, [create one](https://dashboard.plaid.com/signup) . To enable your Plaid account for the integration, go to the [Integrations](https://dashboard.plaid.com/developers/integrations) section of the account dashboard. If the integration is off, simply click the 'Enable' button for Zero Hash to enable the integration. You'll need to complete your Plaid [Application Profile](https://dashboard.plaid.com/settings/company/app-branding) in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks. Finally, you'll need to go to the [Link customization UI](https://dashboard.plaid.com/link/data-transparency-v5) and pick the use cases that you will be using Zero Hash to power, so that Plaid can request the appropriate authorization and consent from your end users. If you have any questions, contact Zero Hash. ##### Create a link\_token  In order to integrate with Plaid Link, you will first need to create a `link_token`. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request with your `client_id`, `secret`, and a few other required parameters from your app server. For a full list of `link_token` configurations, see [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . To see your `client_id` and `secret`, visit the [Plaid Dashboard](https://dashboard.plaid.com/developers/keys) . ```node const request: LinkTokenCreateRequest = { loading_sample: true }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```python request = LinkTokenCreateRequest( loading_sample=True ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "loading_sample": true }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { loading_sample: true } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .loadingSample(true); Response response = client .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```go request := plaid.NewLinkTokenCreateRequest( "Sample App App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetLoadingSample(true) linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := linkTokenCreateResp.GetLinkToken(); ``` ##### Integrate with Plaid Link  Once you have a `link_token`, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the `onSuccess` callback, you can call a simple server-side handler to exchange the Link `public_token` for a Plaid `access_token` and a Zero Hash `processor_token`. Integrate Link ```javascript ``` See the [Link parameter reference](https://plaid.com/docs/link/web/index.html.md#create) for complete documentation on possible configurations. `Plaid.create` accepts one argument, a configuration `Object`, and returns an `Object` with three functions, [open](https://plaid.com/docs/link/web/index.html.md#open) , [exit](https://plaid.com/docs/link/web/index.html.md#exit) , and [destroy](https://plaid.com/docs/link/web/index.html.md#destroy) . Calling `open` will display the "Institution Select" view, calling `exit` will close Link, and calling `destroy` will clean up the iframe. ##### Write server-side handler  The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a `public_token` and an `accounts` array, which is a property on the `metadata` object, via the `onSuccess` callback. Exchange this `public_token` for a Plaid `access_token` using the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) API endpoint. The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. If you want the user to specify only a single account to link so you know which account to use with Zero Hash, set [Account Select](https://dashboard.plaid.com/link/account-select) to "enabled for one account" in the Plaid Dashboard. When this setting is selected, the `accounts` array will always contain exactly one account. Once you have identified the account you will use, you will send the `access_token` and `account_id` property of the account to Plaid via the [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) endpoint in order to create a Zero Hash `processor_token`. You'll send this token to Zero Hash and they will use it to securely retrieve account details from Plaid. You can create Zero Hash `processor_tokens` in both API environments: * Sandbox ([https://sandbox.plaid.com](https://sandbox.plaid.com) ): test simulated users * Production ([https://production.plaid.com](https://production.plaid.com) ): production environment for when you're ready to go live and have valid Zero Hash Production credentials ```node const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest, } = require('plaid'); // Change sandbox to production when you're ready to go live! const configuration = new Configuration({ basePath: PlaidEnvironments[process.env.PLAID_ENV], baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, 'Plaid-Version': '2020-09-14', }, }, }); const plaidClient = new PlaidApi(configuration); try { // Exchange the public_token from Plaid Link for an access token. const tokenResponse = await plaidClient.itemPublicTokenExchange({ public_token: publicToken, }); const accessToken = tokenResponse.data.access_token; // Create a processor token for a specific account id. const request: ProcessorTokenCreateRequest = { access_token: accessToken, account_id: accountID, processor: 'zero_hash', }; const processorTokenResponse = await plaidClient.processorTokenCreate( request, ); const processorToken = processorTokenResponse.data.processor_token; } catch (error) { // handle error } ``` ```bash # Exchange token curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "${PUBLIC_TOKEN}" }' # Create a processor token for a specific account id. curl -X POST https://sandbox.plaid.com/processor/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "${ACCESS_TOKEN}", "account_id": "${ACCOUNT_ID}", "processor": "zero_hash" }' ``` ```ruby require 'plaid' # Change sandbox to production when you're ready to go live! configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] configuration.api_key['Plaid-Version'] = '2020-09-14' api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) # Exchange the public token from Plaid Link for an access token. item_public_token_exchange_request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: public_token } ) exchange_token_response = client.item_public_token_exchange(item_public_token_exchange_request) access_token = exchange_token_response.access_token # Create a processor token for a specific account id. processor_token_create_request = Plaid::ProcessorTokenCreateRequest.new( { access_token: access_token, account_id: account_id, processor: "zero_hash" } ) create_response = client.processor_token_create(processor_token_create_request) processor_token = create_response.processor_token ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; import com.plaid.client.model.ProcessorTokenCreateRequest; import com.plaid.client.model.ProcessorTokenCreateResponse; // Change sandbox to production when you're ready to go live! HashMap apiKeys = new HashMap(); apiKeys.put("clientId", plaidClientId); apiKeys.put("secret", plaidSecret); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange the public token from Plaid Link for an access token. ItemPublicTokenExchangeRequest exchangeRequest = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response exchangeResponse = client() .itemPublicTokenExchange(exchangeRequest) .execute(); // Create a processor token for a specific account id. if (exchangeResponse.isSuccessful()) { String accessToken = exchangeResponse.body().getAccessToken(); ProcessorTokenCreateRequest createRequest = new ProcessorTokenCreateRequest() .accessToken(accessToken) .processor("zero_hash") .accountId("FooBarAccountId"); Response createResponse = client() .processorTokenCreate(createRequest) .execute(); if (createResponse.isSuccessful()) { String processorToken = createResponse.body().getProcessorToken(); } } ``` ```python import plaid from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest from plaid.model.processor_token_create_request import ProcessorTokenCreateRequest # Change sandbox to production when you're ready to go live! configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, 'plaidVersion': '2020-09-14' } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Exchange the public token from Plaid Link for an access token. exchange_request = ItemPublicTokenExchangeRequest(public_token=public_token) exchange_token_response = client.item_public_token_exchange(exchange_request) access_token = exchange_token_response['access_token'] # Create a processor token for a specific account id. create_request = ProcessorTokenCreateRequest( access_token=access_token, account_id=account_id, processor="zero_hash" ) create_response = client.processor_token_create(create_request) processor_token = create_response['processor_token'] ``` ```go import ( "context" "os" plaid "github.com/plaid/v3/plaid-go" ) // create the client configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) // exchange the public_token for an access_token exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *plaid.NewItemPublicTokenExchangeRequest("PUBLIC_TOKEN"), ).Execute() accessToken := exchangePublicTokenResp.GetAccessToken() // get the account id accountsResp, _, err := client.PlaidApi.AccountsGet(ctx).AccountsGetRequest(plaid.AccountsGetRequest{ AccessToken: accessToken, }).Execute() accountID := accountsResp.GetAccounts()[0].GetAccountId() // create a processor token for the specific account id request := plaid.NewProcessorTokenCreateRequest(accessToken, accountID, "zero_hash") stripeTokenResp, _, err := client.PlaidApi.ProcessorTokenCreate(ctx).ProcessorTokenCreateRequest( *request, ).Execute() ``` For a valid request, the API will return a JSON response similar to: Processor token create response ```json { "processor_token": "processor-sandbox-0asd1-a92nc", "request_id": "m8MDnv9okwxFNBV" } ``` For possible error codes, see the full listing of Plaid [error codes](https://plaid.com/docs/errors/index.html.md) . #### Example code in Plaid Pattern  For a real-life example of an app that incorporates the creation of processor tokens, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that creates a processor token to send to your payment partner. The processor token creation code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L126-L135) #### Launching to Production  ##### Test with Sandbox credentials  To test the integration in Sandbox mode, simply use the Plaid [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md) along when launching Link with a `link_token` created in the Sandbox environment. When testing in the Sandbox, you have the option to use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint instead of the end-to-end Link flow to create a `public_token`. When using the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) \-based flow, the Account Select flow will be bypassed and the `accounts` array will not be populated. On Sandbox, instead of using the `accounts` array, you can call [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) and test with any returned account ID associated with an account with the subtype `checking` or `savings`. ##### Get ready for production  Your account is immediately enabled for our Sandbox environment ([https://sandbox.plaid.com](https://sandbox.plaid.com) ). To move to Production, please request access from the [Dashboard](https://dashboard.plaid.com/developers/keys) . You will need Zero Hash Production credentials prior to initiating live traffic in the Zero Hash API with Plaid. ##### Support and questions  Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our [docs](https://plaid.com/docs/index.html.md) . If you're still stuck, open a [support ticket](https://dashboard.plaid.com/support/new) with information describing the issue that you're experiencing and we'll get back to you as soon as we can. --- # Auth - Increasing pay-by-bank adoption | Plaid Docs Increasing pay-by-bank adoption  ================================ #### Enhance discovery and conversion on bank payments via UX design  #### Increasing Pay by bank adoption  Properly presenting 'pay by bank' as a payment method and showcasing the convenience of using Plaid for account authentication can result in up to 2-5x more users choosing to pay by bank. #### Payment method presentation  Place 'Pay by bank' as the first option in a payment list, have it pre-selected with a radio button, and display [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) inline. This shows that instant verification is available and easy to use. (An image of "Payment page with options for monthly, quarterly, or annual plans. 'Pay by bank' is selected. Bank logos displayed for selection. Total: $47.49/month.") Example of Embedded Institution Search on Desktop ##### Embedded Institution Select default open  Users are more likely to select 'Pay by bank' if they understand that it will be a secure, open banking-powered experience, rather than having to enter an account and routing number, which is their default expectation. Users are even more likely to use pay by bank if they see their bank's logo within Link. Plaid will dynamically show the user the most popular institutions for your application in their area, or you can customize this list via the Plaid Dashboard, under [Link->Link Customization->Institution Select](https://dashboard.plaid.com/link/institution-select) . ###### Recommendations:  * Show as many logos as possible, following the [breakpoint guidance](https://plaid.com/docs/link/embedded-institution-search/index.html.md#customization-options) , in order to increase the likelihood that the user will see their bank. * By providing the user's phone number when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , you can activate the streamlined version of [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md#pre-filling-phone-numbers-for-faster-account-verification) , which has been shown to drive a 2x increase in bank payments adoption for returning users. * Ensure Embedded Institution Search is visible by default, without requiring the user to first select 'Pay by bank'. #### Using accordion open  If the Embedded Institution Search inline display option is not available to you due to design or technical constraints, use an "accordion open" technique. Once the user selects 'Pay by bank', render the Embedded Institution Search for easy user comprehension of their next steps to add a bank account. (An image of "Payment page with options for monthly, quarterly, annual plans. Select pay by bank or card. Pet insurance $47.49/month. Pay button.") Example of Embedded Institution Search on Desktop ###### Recommendations:  * Labeling the payment method as 'Pay by bank' and adding an appropriate CTA such as 'instantly verify your bank account' will help users understand that your pay by bank flow is powered by open banking. * Use "accordion open" if necessary to display Embedded Institution Search. #### Configure Account Select  The [Account Select](https://plaid.com/docs/link/customization/index.html.md#account-select) option "Enabled for one account" setting configures the Link UI so that the end user may only select a single account. This is the appropriate configuration for most pay-by-bank use cases. You can configure this option in the Dashboard, under [Link > Link Customization > Account Select](https://dashboard.plaid.com/link/account-select) . #### Enable Database Auth  Although most users prefer signing into their bank account via open banking, some prefer to provide their account and routing numbers manually. ##### Recommendations:  * To support both populations, enable [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) . Database Auth is appropriate for low-to-medium-risk scenarios, such as recurring bill payments and loan repayments. If you experience high rates of fraud or ACH returns in your payments flow, you should not enable Database Auth. #### Auth Type Select  For user populations with a higher propensity to link accounts manually, Plaid provides [Auth Type Select](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#adding-manual-verification-entry-points-with-auth-type-select) as an upfront option to the end user to choose between open banking login or manual account connection. Otherwise, this option will only be displayed if the user can't find their bank or encounters an error trying to connect. Examples of populations that may prefer manually linking include business users (who may not have access to their organization's online banking credentials) or users who are less comfortable with technology. (An image of "Pay by bank: Select payment method with bank search and Auth Type Select. Monthly plan, $47.49/mo summary visible.") Embedded Institution Search with Auth Type Select enabled Auth Type Select will increase the percentage of users whose proposed payments cannot be evaluated for risk. Use [Signal Transaction Scores](https://plaid.com/docs/signal/signal-rules/index.html.md#data-availability-limitations) and [Identity Match](https://plaid.com/docs/identity/index.html.md#using-identity-match-with-micro-deposit-or-database-items) with manually verified Items to reduce the risk of return. If you experience high rates of fraud or ACH returns in your payments flow, you should not enable Auth Type Select. ##### Recommendations:  * Enable [Auth Type Select](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#adding-manual-verification-entry-points-with-auth-type-select) if you have reason to believe that your user population prefers to link accounts manually and your risk profile can tolerate lower coverage of anti-fraud and anti-ACH-return checks. --- # Balance - Add Balance to your app | Plaid Docs Add Balance to your app  ======================== #### Use Balance to fetch real-time balance data  In this guide, we'll start from scratch and walk through how to use Balance to retrieve real-time balance information and assess ACH return risk. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, make sure to note that you should _not_ include `balance` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) products array, but you _should_ include `signal`, if you are using Balance for an ACH risk assessment use case; you can then skip ahead to [Fetching balance data](https://plaid.com/docs/balance/add-to-app/index.html.md#fetching-balance-data) . #### Get Plaid API keys and complete application and company profile  If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard. You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile and company profile must be completed before connecting to certain institutions in Production. #### Install and initialize Plaid libraries  You can use our official server-side client libraries to connect to the Plaid API from your application: ```node // Install via npm npm install --save plaid ``` ```bash ## Not applicable with curl calls ``` ```ruby # Available as a gem gem install plaid ``` ```java /* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ implementation "com.plaid:plaid-java:{VERSION}" /* For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ com.plaid plaid-java {VERSION} ``` ```python # Install through pip, only supports Python 3 pip install --upgrade plaid-python ``` ```go go get github.com/plaid/plaid-go ``` After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls. ```node // Using Express const express = require('express'); const app = express(); app.use(express.json()); const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const client = new PlaidApi(configuration); ``` ```bash ## Not applicable with curl calls ``` ```ruby require 'sinatra' require 'plaid' set :port, ENV['APP_PORT'] || 8000 configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) ``` ```java import java.net.*; import java.io.*; import retrofit2.Response; import java.util.Arrays; import com.sun.net.httpserver.*; import com.plaid.client.ApiClient; import com.plaid.client.request.PlaidApi; public class PlaidExample { private static final String CLIENT_ID = System.getenv("PLAID_CLIENT_ID"); private static final String SECRET = System.getenv("PLAID_SECRET"); public static void main(String[] args) { HttpServer server = HttpServer.create( new InetSocketAddress("localhost", 8000), 0); server.createContext("/create_link_token", new GetLinkToken()); server.setExecutor(null); server.start(); } // Additional server code goes here } ``` ```python import plaid from plaid.api import plaid_api from flask import Flask from flask import render_template from flask import request from flask import jsonify app = Flask(name) configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Additional server code goes here if __name__ == "__main__": app.run(port=8000) ``` ```go import ( "context" "net/http" "os" "github.com/gin-gonic/gin" "github.com/plaid/plaid-go/v3/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) func main() { r := gin.Default() // Server endpoints would be declared here // e.g. r.POST("/create_link_token", createLinkToken) r.POST("/create_link_token", createLinkToken) err := r.Run(":8000") if err != nil { panic("unable to start server") } } ``` #### Create an Item in Link  Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) . If you are using Balance for a payments use case and you do not set the [Link Account Select UI](https://dashboard.plaid.com/link/account-select) to "enabled for one account", your UI flow when creating a payment must handle the scenario of an end user linking an Item with multiple accounts and allow them to specify which account to use for the payment. In order to launch Link in Production, you must [select use cases for your Link customization](https://dashboard.plaid.com/link/data-transparency-v5) . This requirement is not enforced in Sandbox. Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created. If using Balance for ACH return risk assessment, include `signal` in the `products` array, along with all other Plaid product(s) you will be using with Balance. For all other Balance use cases, omit `signal`, but instead include the Plaid product(s) you will be using with Balance in the `products` array. `balance` cannot be included in the `products` array when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . ##### Create a link\_token  ```node app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['signal, auth'], language: 'en', webhook: 'https://webhook.example.com', redirect_uri: 'https://domainname.com/oauth-page.html', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "products": ["signal, auth"], "country_codes": ["US"], "language": "en", "webhook": "https://webhook.example.com", "redirect_uri": "https://domainname.com/oauth-page.html" }' ``` ```ruby post '/api/create_link_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: client_user_id }, client_name: 'Plaid Test App', products: ['signal, auth'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.example.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.Products; import com.plaid.client.model.CountryCode; import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; public class PlaidExample { ... static class GetLinkToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.fromValue("signal, auth"))) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .redirectUri("https://domainname.com/oauth-page.html") .webhook("https://webhook.example.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.link_token_create_request import LinkTokenCreateRequest from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser from plaid.model.products import Products from plaid.model.country_code import CountryCode @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( products=[Products("signal, auth")], client_name="Plaid Test App", country_codes=[CountryCode('US')], redirect_uri='https://domainname.com/oauth-page.html', language='en', webhook='https://webhook.example.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetRedirectUri("https://domainname.com/oauth-page.html") request.SetProducts([]plaid.Products{plaid.PRODUCTS_SIGNAL, AUTH}) resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` ##### Install Link dependency  index.html ```html Connect a bank ``` ##### Configure the client-side Link handler  app.js ```javascript const linkHandler = Plaid.create({ token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token to your app server. $.post('/exchange_public_token', { public_token: public_token, }); }, onExit: (err, metadata) => { // Optionally capture when your user exited the Link flow. // Storing this information can be helpful for support. }, onEvent: (eventName, metadata) => { // Optionally capture Link flow events, streamed through // this callback as your users connect an Item to Plaid. }, }); linkHandler.open(); ``` #### Get a persistent access\_token  Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call. Save the `access_token` and `item_id` in a secure datastore, as they're used to access `Item` data and identify `webhooks`, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it. ```node app.post('/api/exchange_public_token', async function ( request, response, next, ) { const publicToken = request.body.public_token; try { const tokenResponse = await client.itemPublicTokenExchange({ public_token: publicToken, }); // These values should be saved to a persistent database and // associated with the currently signed-in user const accessToken = tokenResponse.data.access_token; const itemID = tokenResponse.data.item_id; response.json({ public_token_exchange: 'complete' }); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-12345678-abcd-1234-abcd-1234567890ab" }' ``` ```ruby access_token = nil post '/api/exchange_public_token' do request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: params["public_token"] } ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response.access_token item_id = response.item_id content_type :json {public_token_exchange: "complete"}.to_json end ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; public class PlaidExample { ... static class GetAccessToken implements HttpHandler { private static PlaidClient plaidClient; private String publicToken; private String accessToken; private String itemId; public void handle(HttpExchange t) throws IOException { // Simplified pseudo-code for obtaining public_token InputStream is = t.getRequestBody(); publicToken = is.publicToken(); // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange public_token for an access_token ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response response = plaidClient .itemPublicTokenExchange(request) .execute(); // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken = response.body().getAccessToken(); itemId = response.body().getItemId(); String message = "{\"public_token_exchange\": \"complete\"}"; return Response .status(Response.Status.OK) .entity(message) .type(MediaType.APPLICATION_JSON) } } } ``` ```python access_token = None item_id = None @app.route('/exchange_public_token', methods=['POST']) def exchange_public_token(): global access_token public_token = request.form['public_token'] request = ItemPublicTokenExchangeRequest( public_token=public_token ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response['access_token'] item_id = response['item_id'] return jsonify({'public_token_exchange': 'complete'}) ``` ```go func getAccessToken(c *gin.Context) { ctx := context.Background() publicToken := c.PostForm("public_token") // exchange the public_token for an access_token exchangePublicTokenReq := plaid.NewItemPublicTokenExchangeRequest(publicToken) exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *exchangePublicTokenReq, ).Execute() // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken := exchangePublicTokenResp.GetAccessToken() itemID := exchangePublicTokenResp.GetItemId() c.JSON(http.StatusOK, gin.H{"public_token_exchange": "complete"}) } ``` #### Fetching Balance data  Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. There are two ways to use Balance: by using [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , or by using [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) . If you are using Balance to evaluate a proposed ACH transaction for return risk, use [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) . For all other use cases, use [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) . ##### Using /signal/evaluate  ###### Creating a Balance-only ruleset  In the Dashboard, navigate to [Signal->Rules](https://dashboard.plaid.com/signal/risk-profiles) to create a Balance-only ruleset. When you do, Plaid will pre-populate a suggested ruleset; you can either use it as-is or customize it. In Sandbox, you will be offered a choice between Balance-only and Signal Transaction Score-powered rulesets. To use Balance, select "Balance-only". In Production, Signal Transaction Score rulesets will only be provided as an option if you are Production-enabled for the Signal Transaction Scores product. ###### Getting the account\_id  If you are using [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , you will need to know the `account_id` of the account that is being debited. You can get this in multiple ways, the simplest of which are: by using the `onSuccess` callback in Link (`metadata.accounts[].id`) or by calling [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) . Method 1: The metadata object from Link onSuccess callback ```json { ... "accounts": [ { "id": "ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy", "name": "Plaid Checking", "mask": "0000", "type": "depository", "subtype": "checking", "verification_status": null }, { "id": "9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4", "name": "Plaid Saving", "mask": "1111", "type": "depository", "subtype": "savings" } ], ... } ``` ```bash curl -X POST https://sandbox.plaid.com/accounts/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node const request: AccountsGetRequest = { access_token: ACCESS_TOKEN, }; try { const response = await plaidClient.accountsGet(request); const accounts = response.data.accounts; } catch (error) { // handle error } ``` ```python request = AccountsGetRequest(access_token=ACCESS_TOKEN) response = client.accounts_get(request) accounts = response['accounts'] ``` ```java AccountsGetRequest request = new AccountsGetRequest() .accessToken(ACCESS_TOKEN); Response response = client() .accountsGet(request) .execute(); List accounts = response.body().getAccounts(); ``` ```ruby request = Plaid::AccountsGetRequest.new({ access_token: ACCESS_TOKEN }) response = client.accounts_get(request) accounts = response.accounts ``` ```go accountsGetRequest := plaid.NewAccountsGetRequest(accessToken) accountsGetRequest.SetOptions(plaid.AccountsGetRequestOptions{ AccountIds: &[]string{}, }) accountsGetResp, _, err = client.PlaidApi.AccountsGet(ctx).AccountsGetRequest( *accountsGetRequest, ).Execute() accounts := accountsGetResp.GetAccounts() ``` A sample response is below (note that [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) returns balance data, but it is cached and not updated in real time): /accounts/get response ```json { "accounts": [ { "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "holder_category": "personal", "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" }, { "account_id": "6PdjjRP6LmugpBy5NgQvUqpRXMWxzktg3rwrk", "balances": { "available": null, "current": 23631.9805, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "6666", "name": "Plaid 401k", "official_name": null, "subtype": "401k", "type": "investment" } ], ... ``` Once you have obtained both an `access_token` and an `account_id`, you can call [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) to evaluate the proposed transaction. If you do not specify a `ruleset_key`, the transaction will be evaluated based on the ruleset named `default`. ```node const eval_request = { access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175', account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', client_transaction_id: 'txn12345', amount: 123.45, } try { const eval_response = await plaidClient.signalEvaluate(eval_request); const core_attributes = eval_response.data.core_attributes; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/signal/evaluate \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "client_transaction_id": "txn12345", "amount": 123.45 }' ``` ```ruby request = Plaid::SignalEvaluateRequest.new( { access_token: access_token, account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr', client_transaction_id: 'txn12345', amount: 123.45, } ) response = client.signal_evaluate(request) result = response.ruleset.result ``` ```java SignalEvaluateRequest request = new SignalEvaluateRequest() .accessToken("access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175") .accountId("3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr") .clientTransactionId("txn12345") .amount(123.45); Response response = plaidClient() .signalEvaluate(request) .execute(); RuleResult result = response.body().getRuleset().getResult(); ``` ```python request = SignalEvaluateRequest( access_token="access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", account_id="3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", client_transaction_id="txn123", amount=123.45, ) response = client.signal_evaluate(request) result = response['ruleset']['result'] ``` ```go request := plaid.NewSignalEvaluateRequest( "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175", "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "txn12345", 123.45, ) response, _, err := client.PlaidApi.SignalEvaluate(ctx).SignalEvaluateRequest(*request).Execute() result := response.GetRuleset().GetResult() ``` To determine which action to take, use the `ruleset.result` value of `accept`, `reroute`, or `review`. To learn more about these values, see [Signal rules](https://plaid.com/docs/signal/signal-rules/index.html.md#using-signal-ruleset-results) . You can also view the real-time current and available balances in `core_attributes.current_balance` and `core_attributes.available_balance`. #### Reporting outcomes  If the result was `review`, report your final review decision to Plaid using [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) or by uploading a CSV. For more details, see [Reporting decisions and returns](https://plaid.com/docs/signal/reporting-returns/index.html.md) . ```node const decision_report_request = { client_transaction_id: 'txn12345', initiated: true, days_funds_on_hold: 3, }; try { const decision_report_response = await plaidClient.signalDecisionReport( decision_report_request, ); const decision_request_id = decision_report_response.data.request_id; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/signal/decision/report \ -H 'content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_transaction_id": "txn123", "initiated": true }' ``` ```ruby request = Plaid::SignalDecisionReportRequest.new( { client_transaction_id: 'txn12345', initiated: true, days_funds_on_hold: 3 } ) response = client.signal_decision_report(request) request_id = response.request_id ``` ```java SignalDecisionReportRequest request = new SignalDecisionReportRequest() .clientTransactionId("txn12345") .initiated(true) .daysFundsOnHold(3); Response response = plaidClient() .signalDecisionReport(request) .execute(); String requestID = response.body().getRequestId(); ``` ```python request = SignalDecisionReportRequest( client_transaction_id="txn12345", initiated=True, days_funds_on_hold=3, ) response = client.signal_decision_report(request) request_id = response['request_id'] ``` ```go request := plaid.NewSignalDecisionReportRequest( "txn12345", true, ) request.SetDaysFundsOnHold(3) response, _, err := client.PlaidApi.SignalDecisionReport(ctx).SignalDecisionReportRequest(*request).Execute() request_id := response.GetRequestId() ``` If you allow a transfer that does end up returned, report that result back to Plaid as well. You can do this by calling [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) or by uploading a CSV. For more details, see [Reporting decisions and returns](https://plaid.com/docs/signal/reporting-returns/index.html.md) . ```node const return_report_request = { client_transaction_id: 'txn12345', return_code: 'R01', }; try { const return_report_response = await plaidClient.signalReturnReport( return_report_request, ); const request_id = return_report_response.data.request_id; console.log(request_id); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/signal/return/report \ -H 'content-type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_transaction_id": "txn12345", "return_code": "R01" }' ``` ```ruby request = Plaid::SignalReturnReportRequest.new( { client_transaction_id: 'txn12345', return_code: 'R01' } ) response = client.signal_return_report(request) request_id = response.request_id ``` ```java SignalReturnReportRequest request = new SignalReturnReportRequest() .clientTransactionId("txn12345") .returnCode("R01"); Response response = client() .signalReturnReport(request) .execute(); String requestId = response.body().getRequestId(); ``` ```python request = SignalReturnReportRequest( client_transaction_id="txn12345", return_code="R01", ) response = client.signal_return_report(request) request_id = response['request_id'] ``` ```go request := plaid.NewSignalReturnReportRequest( "txn12345", "R01", ) response, _, err := client.PlaidApi.SignalReturnReport(ctx).SignalReturnReportRequest(*request).Execute() request_id := response.GetRequestId() ``` ##### Using /accounts/balance/get  For more detailed information on the schema returned, see [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) . ```node const { AccountsGetRequest } = require('plaid'); // Pull real-time balance information for each account associated // with the Item const request: AccountsGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.accountsBalanceGet(request); const accounts = response.data.accounts; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/accounts/balance/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "options": { "account_ids": [String] } }' ``` ```ruby # Pull real-time balance information for each account associated # with the Item request = Plaid::AccountsBalanceGetRequest.new({ access_token: access_token }) response = client.accounts_balance_get(request) accounts = response.accounts ``` ```java import com.plaid.client.model.AccountsBalanceGetRequest; import com.plaid.client.model.AccountsGetResponse; // Pull real-time balance information for each account associated // with the Item AccountsBalanceGetRequest request = new AccountsBalanceGetRequest() .accessToken(accessToken); Response response = client() .accountsBalanceGet(request) .execute(); List accounts = response.body().getAccounts(); ``` ```python from plaid.model.accounts_balance_get_request import AccountsBalanceGetRequest # Pull real-time balance information for each account associated # with the Item request = AccountsBalanceGetRequest(access_token=access_token) response = client.accounts_balance_get(request) accounts = response['accounts'] ``` ```go import ( "context" ) balancesGetResp, _, err := client.PlaidApi.AccountsBalanceGet(ctx).AccountsBalanceGetRequest( *plaid.NewAccountsBalanceGetRequest(accessToken), ).Execute() accounts := balancesGetResp.GetAccounts() ``` Example response data is below. Balance sample response ```json { "accounts": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" }, { "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "balances": { "available": null, "current": 410, "iso_currency_code": "USD", "limit": 2000, "unofficial_currency_code": null }, "mask": "3333", "name": "Plaid Credit Card", "official_name": "Plaid Diamond 12.5% APR Interest Credit Card", "subtype": "credit card", "type": "credit" }, { "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE", "balances": { "available": null, "current": 65262, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "7777", "name": "Plaid Student Loan", "official_name": null, "subtype": "student", "type": "loan" } ], "item": { "available_products": [ "balance", "credit_details", "identity", "investments" ], "billed_products": ["assets", "auth", "liabilities", "transactions"], "consent_expiration_time": null, "error": null, "institution_id": "ins_3", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "webhook": "https://www.genericwebhookurl.com/webhook" }, "request_id": "qk5Bxes3gDfv4F2" } ``` #### Next steps  If you're ready to launch to Production, see the Launch checklist. #### Launch checklist  Recommended steps to take before launching in Production [Launch](https://plaid.com/docs/launch-checklist/index.html.md) --- # Balance - Introduction to Balance | Plaid Docs Introduction to Balance   ========================= #### Retrieve real-time balance information  Get started with Balance [API Reference](https://plaid.com/docs/api/products/signal/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md) [Demo](https://plaid.coastdemo.com/share/6786ccc5a048a5f1cf748cb5?zoom=100) #### Overview  Balance is Plaid's product for receiving real-time balance information. This data is commonly used to tell if an account has sufficient funds before using it as a funding source for a payment transaction, helping you to avoid ACH returns. Balance is available for use exclusively in combination with other Plaid products, such as [Auth](https://plaid.com/docs/auth/index.html.md) for money movement or account funding use cases or [Transactions](https://plaid.com/docs/transactions/index.html.md) for personal finance use cases. [Prefer to learn by watching? Get an overview of how Balance works in just 3 minutes!](https://www.youtube.com/watch?v=VfXwIkNsqO8) #### Cached and real-time balance  While you can retrieve balance data via many endpoints, including by calling the free-to-use [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint, this data is cached, making it unsuitable for situations where you need real-time balance information, except immediately after the Item has been added. An Item with Transactions may update cached balances once a day or more, while an Item with only Auth may update cached balances every 30 days or even less frequently. For retrieving real-time balance for payments use cases, only Balance should be used. Because Balance always performs a real-time data extraction, latency is higher than other Plaid endpoints (p50 ~3s, p95 ~11s). To check for ACH return risk in critical user-present flows that require low latency, consider [Signal Transaction Scores](https://plaid.com/docs/signal/index.html.md) . For more details, see [Reducing latency and getting better insights with Signal Transaction Scores](https://plaid.com/docs/balance/index.html.md#reducing-latency-and-getting-better-insights-with-signal-transaction-scores) . #### Balance integration options  There are two options you can use for retrieving balance data: using Signal Rules (with [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) ) or using [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) . While they are priced the same, return the same account data, and have the same latency, each method works differently and is designed for different use cases. ##### Balance using /signal/evaluate  The [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) endpoint is the recommended way to retrieve balance data whenever you are checking balance to evaluate the insufficient funds risk of a proposed ACH transaction. [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) checks balance and returns current and available balance, as well as a recommended action to take (i.e., accept the transaction, review it further, or request a different payment method) based on a ruleset evaluation using [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) . With Signal Rules, you can easily customize your business logic around these recommended actions in a Dashboard-based UI, without making any code changes. (An image of "no description available") Using Balance with Signal Rules in the Dashboard [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) is available for all new Balance customers who received Production access after October 15, 2025. Existing Balance customers will be enabled for [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) in the near future. If you are an existing Balance customer and would like immediate access to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , contact your account manager; for more details, see the [migration guide](https://plaid.com/docs/balance/migration-guide/index.html.md) . ##### Balance using /accounts/balance/get  [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) retrieves balance data, including current and available balance, but does not run Signal Rules. This endpoint is recommended for all use cases where you are _not_ checking balance to evaluate a proposed ACH transaction: for example, if you need real-time balance data for a Personal Financial Management (PFM) use case, or for treasury management, or for any non-US bank account. [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) is also the legacy endpoint for checking balance that many customers use in existing integrations. #### Integration overview using /signal/evaluate  1. [Create a Balance-only Rule](https://plaid.com/docs/signal/signal-rules/index.html.md) in the [Signal Rules Dashboard](https://dashboard.plaid.com/signal/risk-profiles) . 2. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Along with any other parameters you specify, make sure to include the following: * Include `signal` and `auth` in the `products` array, along with any other Plaid product(s) you plan to use. Do _not_ include `balance` in the `products` array. 3. On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . * If you will be using the linked Item as a payment source or destination, it is recommended to [configure your Link customization](https://plaid.com/docs/link/customization/index.html.md) to use the setting [Account Select: Enabled for one account](https://plaid.com/docs/link/customization/index.html.md#account-select) . Otherwise, you will need to build a UI within your app for the user to indicate which account they want to use for the payment, if their bank login is associated with more than one bank account. 4. Once the end user has completed the Link flow, exchange the `public_token` for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . 5. Call [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) and [determine the next steps based on results](https://plaid.com/docs/signal/signal-rules/index.html.md#using-signal-ruleset-results) . 6. [Report ACH returns and decisions](https://plaid.com/docs/signal/reporting-returns/index.html.md) to Plaid. 7. (Optional) After launch, periodically [review and tune your Signal Rules](https://plaid.com/docs/signal/tuning-rules/index.html.md) using the Dashboard. #### Integration overview using /accounts/balance/get  1. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with the product(s) you plan to use. Do _not_ include `balance` in the `products` array. 2. On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . 3. Once the end user has completed the Link flow, exchange the `public_token` for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . 4. Call [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) , passing in the `access_token` returned in step 3. #### Reducing latency and getting better insights with Signal Transaction Scores  For use cases that involve evaluating a proposed ACH transaction to reduce return risk, Balance can be used alongside [Signal Transaction Scores](https://plaid.com/docs/signal/index.html.md) . Signal Transaction Scores has lower latency (p95 <2s versus Balance's 11s), making it ideal for user-present transactions in critical flows such as onboarding or purchasing. With Signal Transaction Scores, you can access 80+ criteria for rule generation and ML-powered recommendations and insights to help you optimize and fine-tune your transaction approval logic. Signal Transaction Scores and Balance are both part of Plaid Signal, Plaid's solution for ACH risk management. You can purchase and use either Balance or Signal Transaction Scores by itself, or combine them for a more comprehensive ACH risk management approach. Once you have integrated Balance using [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , Signal Transaction Scores requires no additional engineering work to integrate. Just use the Signal Rule editor in the Dashboard to upgrade your existing Balance-only rule into a Signal Transaction Score-powered rule. To learn more, or to request access to Signal Transaction Scores, contact [sales](https://plaid.com/contact/) or your account manager. #### Migration guide  If you are an existing customer and would like to migrate from [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) to take advantage of Signal Rules, see the [Balance migration guide](https://plaid.com/docs/balance/migration-guide/index.html.md) . #### Current and available balance  Banks represent balance with two separate values, current balance and available balance. For assessing ACH risk, available balance is often more important than current balance, as it represents predicted balance net of any pending transactions, while current balance does not take pending transactions into account. For credit accounts, available balance indicates the amount that can be spent without hitting the credit limit (net of any pending transactions), while in investment accounts, it indicates the total available cash. In some cases, a financial institution may not provide available balance information. If necessary, you can often calculate available balance by starting with the current balance, then using the [Transactions](https://plaid.com/docs/transactions/index.html.md) product to detect any pending transactions and adjusting the balance accordingly. ##### Typical balance fill rates by field  | Field | Typical fill rate | | --- | --- | | Current balance | 99% | | Available balance | 91% | #### Balance pricing  Balance is billed on a [flat fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) , meaning you will be billed once for each successful call to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) or [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) . [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) (when used with a Balance-only ruleset) and [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) are billed at the same rate. When using [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , you will be billed if the API call is successful, even if balance extraction fails. To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) . #### Next steps  To get started building with Balance, see [Add Balance to your App](https://plaid.com/docs/balance/add-to-app/index.html.md) . If you're ready to launch to Production, see the Launch Center. #### Launch Center  See next steps to launch in Production [Launch](https://dashboard.plaid.com/developers/launch-center) --- # Balance - Migrate to Signal Rules | Plaid Docs Balance migration guide  ======================== #### Why migrate?  If you use Balance to reduce ACH return risk, migrating your integration from [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) and Signal Rules provides the following benefits: * Configure and customize business logic for accepting transactions in the [Signal Dashboard](https://dashboard.plaid.com/signal/) , without making any code changes. * View your transaction return activity and performance via the Dashboard. * Access [personalized recommendations and scenario modeling](https://plaid.com/docs/signal/tuning-rules/index.html.md) to help tune and optimize your rules. * If you need to upgrade certain balance checks to using Signal Transaction Scores for lower latency, deeper insights, or more sophisticated rules logic, you can do so without any code changes. Note: Signal Rules and [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) are only available for use cases involving evaluating potential ACH transactions for return risk. Other Balance use cases should continue to use [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) . #### Migration steps  Signal Rules will be available soon for all existing Balance customers. In the meantime, if you would like to migrate to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , contact your account manager to request access. 1. Configure the [Signal Rules](https://dashboard.plaid.com/signal/risk-profiles) in the Dashboard to create a **Balance-only Ruleset** that matches your existing business logic. For more details, see [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) . 2. Replace your [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) calls with calls to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) . At a minimum, you will need to send the following parameters: * The `access_token` * The `account_id` of the account you will be debiting * The transaction `amount` * A `client_transaction_id` of your choosing to uniquely identify the proposed transaction * The `ruleset_key` you want to use, if you are using multiple rulesets (will default to using the `default` ruleset if not specified) 3. [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) will return a `ruleset.result` such as `ACCEPT` or `REROUTE`, based on your ruleset logic. In your application's code, replace the balance-based logic around accepting or rerouting a proposed transaction to instead use the value of this field. 4. If you still need direct access to real-time balance data (for example, to display in your UI) you can access it via the `core_attributes.available_balance` and `core_attributes.current_balance` fields returned by [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) . 5. [Report whether you proceeded with the transaction](https://plaid.com/docs/signal/reporting-returns/index.html.md) by calling [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) . You only need to do this if the result was `REVIEW`, or if you did not follow the recommendation in the result (e.g. accepted a transaction even if the result was `REROUTE`). 6. If you later receive an ACH return for an accepted transaction, call [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) . --- # Beacon - Introduction to Beacon | Plaid Docs Introduction to Beacon (beta)   =============================== #### Learn how to fight fraud with the Plaid Beacon network  #### API Reference  View Beacon requests, responses, and example code [View Beacon API](https://plaid.com/docs/api/products/beacon/index.html.md) #### Overview  The Beacon beta program is now closed. Customers who are not already using Beacon should instead use the newer [Plaid Protect](https://plaid.com/products/protect/) , which incorporates Beacon's capabilities and enhances them with additional fraud insights. Beacon (US only) helps prevent fraud by detecting data associated with stolen or synthetic identities, account takeover fraud, or breaches. You can create blocklists based on data reported by the Beacon network, or based on first-party fraud attempts on your own app. Beacon is available free of charge. An optional paid feature, Beacon Account Insights, is available to customers who want to build their own risk analysis on top of Plaid's Beacon data. Beacon Account Insights includes risk-related details such as account age, recent PII changes on the account, and recent failed login attempts. For a full list of data reported by Bank Account Insights, see the [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) response schema. #### Integration setup  Select group for content switcher Without Identity VerificationWith Identity Verification ##### Initial setup  1. [Create a Beacon program](https://dashboard.plaid.com/sandbox/beacon/programs/new) via the Dashboard. * For best results, disable "auto flag reported user" under the "data breach hits" section, unless you have a specific business reason to enable it. Because so many users have been exposed to data breaches, enabling auto-flagging for data breach hits will result in a large number of users entering the review queue. All other automatically-selected options should be left enabled for most use cases. 2. Take note of the beacon program ID, which is the portion of the URL after the `/` when viewing the program in the Dashboard, e.g. `becprg_7Fn5XcPhXnJJyU`. You will need this id when calling [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) and other endpoints. 3. (Optional) For best results, backfill six months of existing data into Beacon. This should include both known-good and known-fraudulent users. To backfill, call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) for each user, making sure to include any known instances of fraud in the `report` object. Make sure to always use the same `client_user_id` when referring to the same end user, whenever you call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) , [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) , or [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . ##### User creation  1. To create a new user, call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) . 2. (Optional) To be alerted for the accidental creation of potential duplicate users, listen for the [DUPLICATE\_DETECTED](https://plaid.com/docs/api/products/beacon/index.html.md#duplicate_detected) webhook. You can investigate potential duplicates via the Dashboard (when configuring your Beacon template, you can set all detected duplicates to enter the review queue by default) or by calling [/beacon/duplicate/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconduplicateget) . ##### Reviewing and reporting fraud signals  1. Review any Beacon hits via the Dashboard, to clear or reject the user. 2. If you become aware of any fraud committed by a user, report it to the network by clicking the "Report Fraud" button in the Beacon Dashboard or by calling [/beacon/report/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportcreate) . To learn more about how to properly categorize fraud, see the [Fraud Reporting Guide](https://view-su2.highspot.com/viewer/3ba173969f637a61e6e9d8e41eba083b) . 3. (Optional) To monitor for fraud on an ongoing basis, listen for the [REPORT\_SYNDICATION\_CREATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_syndication_created) webhook to be alerted to new fraud reports for any Beacon user in your system. When this webhook fires, to get more details on the report, use the Dashboard, or call [/beacon/report\_syndication/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationget) . 4. (Optional) If you are monitoring for fraud on an ongoing basis, call [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) when you are aware of any changes to user data (such as name, address or phone number) or if the user links a new account. Calling [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) will immediately re-run fraud checks for the user and may generate Beacon hits. ##### Using Beacon Account Insights (optional)  Beacon Account Insights is an optional paid feature that allows you to build your own risk analysis on top of Plaid-reported risk signals. Reported risk signals include account age, recent PII changes on the account, and recent failed login attempts. For a full list of returned fields, see the API Reference for [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) . 1. Create a Link token and use it to launch Link, following the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform. When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , be sure to include `beacon` in the `products` array. 2. The end user will then complete a Link session, resulting in a `public_token`, which can be obtained by either the `onSuccess` client-side callback or by calling [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) . 3. Use [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` for an `access_token`. 4. Call [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) to associate the `access_token` with the Beacon user. 5. Call [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) to get account insights. Before following these steps, set up [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) following the [Identity Verification integration process](https://plaid.com/docs/identity-verification/index.html.md#identity-verification-integration-process) . ##### Initial setup  1. [Create a Beacon program](https://dashboard.plaid.com/sandbox/beacon/programs/new) via the Dashboard. * For best results, disable "auto flag reported user" under the "data breach hits" section, unless you have a specific business reason to enable it. Because so many users have been exposed to data breaches, enabling auto-flagging for data breach hits will result in a large number of users entering the review queue. All other automatically-selected options should be left enabled for most use cases. 2. Open the Identity Verification template editor and select your Beacon program under Setup > Beacon Fraud Screening, then click "publish". 3. (Optional) For best results, backfill six months of existing data into Beacon. * If you are adding Beacon to an Identity Verification deployment that has already been running in Production, then to backfill, call [/beacon/report/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportcreate) to report each known incident of fraud, using the `beacon_user_id` obtained from calling [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) , and making sure to include any known instances of fraud in the `report` object. * To backfill users that have _not_ been through an Identity Verification session, call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) for each user, making sure to include any known instances of fraud in the `report` object. Make sure to always use the same `client_user_id` when referring to the same end user, whenever you call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) , [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) , or [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . ##### User creation  1. To add a new user, launch Link as normal and have the user go through an Identity Verification session. You should _not_ update the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) `products` array to include `beacon`. 2. To get the `beacon_id` for the user, call [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) . There is no need to call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) . ##### Reviewing and reporting fraud signals  1. Review any Beacon hits via the Dashboard, to clear or reject the user. 2. If you become aware of any fraud committed by a user, report it to the network by clicking the "Report Fraud" button in the Beacon Dashboard or by calling [/beacon/report/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportcreate) . To learn more about how to properly categorize fraud, see the [Fraud Reporting Guide](https://view-su2.highspot.com/viewer/3ba173969f637a61e6e9d8e41eba083b) . 3. (Optional) To monitor for fraud on an ongoing basis, listen for the [REPORT\_SYNDICATION\_CREATED](https://plaid.com/docs/api/products/beacon/index.html.md#report_syndication_created) webhook to be alerted to any new fraud reports. 4. (Optional) If you are monitoring for fraud on an ongoing basis, call [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) when you are aware of any changes to user data (such as name, address or phone number) or if the user links a new account. Calling [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) will immediately re-run fraud checks for the user and may generate Beacon hits. In the Link flow, a user will see a "successfully verified" screen if there were no Beacon (or Monitor, if using) hits and all required Identity Verification checks passed. If there were any hits, or if Identity Verification checks failed, the user will see the "verification failed" screen and be placed in the pending review state, where you can review their session from the Dashboard. ##### Using Beacon Account Insights (optional)  Beacon Account Insights is an optional paid feature that allows you to build your own risk analysis on top of Plaid-reported risk signals. Reported risk signals include account age, recent PII changes on the account, and recent failed login attempts. For a full list of returned fields, see the API Reference for [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) . 1. Create a Link token and use it to launch Link, following the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform. When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , be sure to include `beacon` in the `products` array. 2. The end user will then complete a Link session, resulting in a `public_token`, which can be obtained by either the `onSuccess` client-side callback or by calling [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) . 3. Use [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` for an `access_token`. 4. Call [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) to associate the `access_token` with the Beacon user. 5. Call [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) to get account insights. #### Adding Beacon Account Insights to existing Items  1. Send the Item through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . Beacon does not yet support `additional_consented_products`; you will set `"products": ["beacon"]` when initializing update mode. 2. Call [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) (or, if the user was already created, [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) ), providing the Item's `access_token`(s), to associate the Beacon user with the Item. 3. Call [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) to get account insights. #### Beacon workflows  All Beacon hits generate a `pending_review` status and must be reviewed in the Dashboard to resolve into a `cleared` or `rejected` state, unless the hit is for a first-party fraud report generated by your organization. Those hits will move the user directly to a `rejected` status. When creating your Beacon template, you can optionally configure whether a detected duplicate should be moved into `pending_review` state. #### Testing Beacon in Sandbox  In Sandbox, use the [Leslie Knope test user](https://plaid.com/docs/identity-verification/testing/index.html.md#primary-test-user-leslie-knope) to generate Beacon hits and test the Pending Review state. To generate a Cleared status, you can use any user data that you have not already screened. To generate a Rejected status, run a Beacon screening, report a `first_party` fraud incident associated with the user, then run another screening on the user. When testing in Sandbox, re-using the same test user repeatedly will degrade performance over time. If running automated test suites, use randomly generated user data, rather than re-using the same data, in order to avoid performance issues. Similarly, it is not recommended to create large number of duplicate users to test duplicate user detection. #### Beacon pricing  Participation in the Plaid Beacon Network is free of charge. The optional Beacon Account Insights feature, using the [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) endpoint, is billed under [a per-request flat fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . --- # Changelog | Plaid Docs Plaid changelog  ================ #### Track changes to the Plaid API and products  #### Overview  This changelog tracks updates to the Plaid API and changes to the Plaid mobile SDKs, Link flow, functionality, and APIs. The changelog is updated at least once per month. Updates that affect only products or features in beta or limited release may not always be reflected. Improvements to the Dashboard, institution connectivity / Item health, or data availability and quality may not always be reflected. Link SDKs are released on GitHub. A summary of updates will be posted here. For a more complete and detailed record of Link SDK changes, see the GitHub changelogs: [iOS](https://github.com/plaid/plaid-link-ios/releases) , [Android](https://github.com/plaid/plaid-link-android/releases) , [React Native](https://github.com/plaid/react-native-plaid-link-sdk/releases) , [React](https://github.com/plaid/react-plaid-link) . Plaid's officially supported libraries are updated frequently. For details, see the GitHub changelogs: [Python](https://github.com/plaid/plaid-python/blob/master/CHANGELOG.md) , [Node](https://github.com/plaid/plaid-node/blob/master/CHANGELOG.md) , [Ruby](https://github.com/plaid/plaid-ruby/blob/master/CHANGELOG.md) , [Java](https://github.com/plaid/plaid-java/blob/master/CHANGELOG.md) , [Go](https://github.com/plaid/plaid-go/blob/master/CHANGELOG.md) . #### Subscribe to updates  [Subscribe to this changelog via RSS](https://cdn.feedcontrol.net/8259/13425-kjU6T4Te5FUvO.xml) . ##### April 30, 2026  * To align with updated PNC TAN expiration policies, Plaid has stopped firing the `USER_PERMISSION_REVOKED` webhook on standard access expirations at PNC. For Auth: * Announced that by default, limited purpose checking accounts will be omitted from Link. These accounts are not supported by Plaid Balance and only allow ACH payments for mortgage and rent payments. This change will be effective immediately for any new institutions and will be effective August 7, 2026, for existing institutions that are already supported by Plaid. To opt in to allowing limited purpose checking accounts, see [Enabling limited purpose checking accounts for rent or mortgage](https://plaid.com/docs/auth/index.html.md#enabling-limited-purpose-checking-accounts-for-rent-or-mortgage) . For Identity Verification: * Customers can now use the Sample Identities Manager to create and manage IDV test users via the Dashboard, rather than having to request that their account manager create and edit users for them. * Announced a change to Sandbox test user behavior for non-US identities beginning on May 13, 2026: only the "Leslie Knope" user will pass name verification by default. All other identities will require a matching sample identity to pass. For Layer: * Added the ability to exclude users whose provided addresses are non-residential (e.g. PO boxes or commercial addresses) from Layer eligibility. This setting can be enabled via the Layer template editor. For Plaid Check Consumer Report: * Publicly launched [Income Insights v2](https://plaid.com/blog/meet-the-new-engine-behind-plaid-income/) , including improved income categorization accuracy, automatic refresh, and configurable rules for determining how to treat different income sources. ##### April 16, 2026  * Released the [Plaid CLI](https://plaid.com/docs/resources/cli/index.html.md) . The Plaid CLI is an experimental command-line tool for the Plaid API that lets you make API calls for Transactions, Investments, and Liabilities, without writing any code. It works for both developers (with readable table output) and AI agents (with JSON output and clean stdout/stderr separation), and also handles integration tasks like managing API keys, registering webhooks, and working with Sandbox data. * Introduced [Plaid Trial plans](https://plaid.com/docs/sandbox/index.html.md#testing-with-live-data-using-a-trial-plan) . Trial plans provide free access to Production for up to 10 Items and use a streamlined approval questionnaire that is more user-friendly for non-business users. Trial plans replace Limited Production for all newly created Plaid teams going forward. * Added "Sign in with Google" support to the Dashboard. * For the `PENDING_DISCONNECT` webhook, added `disconnect_time` field with a timestamp indicating when the Item's consent will expire. For Plaid Check Consumer Report: * Added `home_lending_report_options` field for configuring Home Lending Report generation (VOA, Employment Refresh) on base report creation. ##### March 31, 2026  * Released [iOS SDK](https://github.com/plaid/plaid-link-ios) v.7.0.0-beta2 and 7.0.0-beta3. Key enhancements over the 6.x SDK series include over 50% reduction in bundle size, native SwiftUI support, and separation of session initialization from UI Link display. For more details, see the [release notes](https://github.com/plaid/plaid-link-ios/releases/tag/7.0.0-beta3) . * Released [iOS SDK](https://github.com/plaid/plaid-link-ios) v. 6.4.5, 6.4.6, and 6.4.7, including bug fixes related to FinanceKit Sync API deprecation and to a bug in `SubmissionData` handling that was introduced in v6.4.3. For Enrich: * Removed unused `recurrence` object. This object was unused and returned placeholder data only, causing confusion for customers. For Investments: * Added `cfi_code` to securities objects. * Added `margin_loan_amount` as an account balance field (in addition to `available` and `current` balance). For Plaid Check Consumer Report: * Customers who began using Plaid Check before December 10, 2025 can now voluntarily migrate to the new User APIs, beginning April 1, 2026. For instructions, see [New User APIs migration guide](https://plaid.com/docs/api/users/migrate-to-new-user-apis/index.html.md) . * Updated the `INTERNAL_SERVER_ERROR` 500 error returned by verification endpoints when data was not ready yet to a retryable `PRODUCT_NOT_READY` 400 error. * Added support for Prism CashScore scoring model v. 4.1 to Partner Insights. For Plaid Protect: * Plaid Protect has been moved from beta to early availability. If you are an existing Plaid customer interested in accessing Protect, contact your account manager. For Signal Transaction Scores and Balance: * Added the ability to create custom Signal Rules targeting specific financial institutions. This functionality is available to both Balance-only and Signal Transaction Score-based rulesets. ##### March 12, 2026  * Released [iOS SDK](https://github.com/plaid/plaid-link-ios) v.7.0.0-beta1. Key enhancements include over 50% reduction in bundle size, native SwiftUI support, and separation of session initialization from UI Link display. For more details, see the [release notes](https://github.com/plaid/plaid-link-ios/releases/tag/7.0.0-beta1) . * Released [iOS SDK](https://github.com/plaid/plaid-link-ios) v6.4.4. Adds event names `SELECT_FALLBACK_ROUTING_INSTITUTION`, `SELECT_DENYLISTED_INSTITUTION`, and `SELECT_REMEMBER_ME_DUPLICATE_INSTITUTION`, deprecates FinanceKit sync API, and deprecates CocoaPods integration. * Updated disclosure copy in Link for Signal Transaction Scores and Protect to enable more workflows without having to use update mode. * Added the ability to set available balance to `null` when using [Custom Sandbox users](https://plaid.com/docs/sandbox/user-custom/index.html.md) . ##### February 26, 2026  * Updated the error object inside of webhooks to return `display_message: null` rather than omitting the `display_message` field if there is no associated display message, in order to match the documented behavior, as well as the behavior of error objects that are returned by the Plaid API outside of a webhook context. For Auth: * Stripe has announced that it will begin to migrate existing customers off of the older Charges and Sources API. Plaid has directly reached out to all impacted customers using the Stripe Charges and Sources x Plaid Auth integration with a list of options for moving forward. If you believe you may be impacted but did not receive an email, contact your Plaid account manager or support. Note that this change does not impact users of the newer Stripe Payment Intents integration (most customers who integrated Stripe x Plaid in 2024 or later are using this newer API). In addition, new customers integrating with Stripe x Plaid for the first time must use the Payment Intents API going forward and can no longer use Charges and Sources. * Released access to Database Auth via API, using the [/auth/verify](https://plaid.com/docs/api/products/auth/index.html.md#authverify) endpoint. This feature is currently in early availability; to request access, contact your Plaid account manager. For Plaid Check Consumer Report: * Beginning March 3, 2026, the `consumer_report_permissible_purpose` field must be included in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) when creating a Link token for a Consumer Report product. Existing customers who are impacted by this change have been contacted by their account managers and may have arranged custom migration deadlines. * Announced April 1, 2026 as the beginning date for the optional migration to [User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . To enable this migration, on April 1, existing customers on the older APIs will begin to get both the new and old webhook versions for revised webhooks. ##### February 18, 2026  * Added [Domains](https://plaid.com/docs/account/teams/index.html.md#team-domains) functionality to Dashboard, enabling the ability to associate a domain with a Plaid team and automatically invite all new Dashboard users with a verified email address matching that domain to join your Plaid team. * Added `user_id` field to webhook payloads for the following webhooks: `SYNC_UPDATES_AVAILABLE`, `PENDING_EXPIRATION`, `ERROR`, `LOGIN_REPAIRED`, `INVESTMENTS_TRANSACTIONS: DEFAULT_UPDATE`, `INVESTMENTS_TRANSACTIONS: HISTORICAL_UPDATE`, `HOLDINGS: DEFAULT_UPDATE`, `LIABILITIES: DEFAULT_UPDATE`, `PENDING_DISCONNECT`, `USER_PERMISSION_REVOKED`, `NEW_ACCOUNTS_AVAILABLE`, `USER_ACCOUNT_REVOKED`, `SESSION_FINISHED`. * Released the [React Native SDK version 12.8](https://github.com/plaid/react-native-plaid-link-sdk/) , with bug fixes for Layer events and Android Proguard rules. * Announced the dates of the Bank of America API migration. From February through mid March 2026, the new API is being gradually rolled out for new Items. Throughout the period of mid March 2026 - late October 2026, existing Items will gradually be disconnected from the old Bank of America API and must be connected to the new Bank of America API by going through update mode. To minimize disruptions, listen for the `PENDING_DISCONNECT` webhook. Upon receiving the webhook, prompt the user to go through the Update Mode flow for the Item, which will migrate the Item to the new API. One week after the `PENDING_DISCONNECT` webhook was fired for a given Item, if the Item has not yet gone through update mode, it will be disconnected from the old API and will enter the `ITEM_LOGIN_REQUIRED` error state. Sending the Item through update mode will move it to the new API and restore it to a healthy state. For Plaid Check Consumer Report: * Added new permissible purpose for Consumer Report generation, `ELIGIBILITY_FOR_GOVT_BENEFITS`, to represent reports generated in connection with an eligibility determination for a government benefit where the entity is required to consider an applicant's financial status pursuant to FCRA Section 604(a)(3)(D). For Layer: * In the `/user_accounts/session/get` response, added `edits_current` field to the `identity_edit_history` object, indicating how many times the user manually edited the prefilled data provided by Layer. ##### February 4, 2026  For Identity Verification: * For the Document Verification flow, enhanced accuracy at detecting when the document presented is not a physical document. These enhancements will be applied automatically; customers do not need to take any action. For Layer: * Released Intelligent Account Sorting. By default, Layer orders accounts in Link based on which one is likeliest to have the highest conversion. With Intelligent Account Sorting, you can instead prioritize either the highest-balance account or the account that Plaid detects as being the user's primary bank account. The prioritized account will have a "Recommended" badge displayed next to it in Link. Intelligent Account Sorting may be a good fit for customers are using Layer in flows for cashflow underwriting, EWA, or cash advance. To enable Intelligent Account Sorting, contact your Plaid account manager, and specify which prioritization scheme (primary account or highest balance account) you prefer and which Link customizations the scheme should be applied to. For Protect: * Added `environment` field to Protect webhooks. For Signal: * Signal is now visible in the Dashboard left navigation for all customers. This change allows all customers to build with Signal Rules in Sandbox, even before they have been approved for Production access. For Virtual Accounts: * Added `payee_verification_status` field to `WalletTransaction` schema. This field indicates the result of payee verification checks for EUR payouts. ##### January 16, 2026  * Starting in late January or early February 2026, Plaid will begin enforcing data validity for user information included in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) API requests. If a phone number, address, name, or email sent in the user object is malformatted, the call will fail with the error `INVALID_USER_IDENTITY_DATA`. This will not impact integrations that do not send user PII in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . * Released [iOS SDK](https://github.com/plaid/plaid-link-ios) v6.4.3, adding support for certain experimental and/or limited-availability Layer features. For Transfer: * Starting in early February 2026, the cutoff time for Same-Day ACH transfers will move from 3:30pm ET to 3:00pm ET. ##### January 2, 2026  For Identity Verification: * Added "Explore" Dashboard view, allowing for backtesting and exploration of rule outcomes and the ability to build custom rules based on specific user and session attributes. To access Explore, go to the [Plaid Protect section of the Dashboard](https://dashboard.plaid.com/protect) . This view is available to all Identity Verification customers based in the US or UK. ##### December 16, 2025  For Identity Verification: * Added `facial_duplicates` object, containing details about facial duplicate results, to `risk_check` object. * Made Trust Index scores accessible via the API, as well as via the Dashboard. For Plaid Check Consumer Report: * Redesigned the PDF report returned by [/cra/check\_report/verification/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationget) , including a detailed overview of a borrower's connected accounts with current and average balances, a breakout of deposits and withdrawals, and total inflows/outflows for each account. ##### December 10, 2025  * Announced upcoming Bank of America API migration and consent expiration. Existing Bank of America Items can be migrated to the new Bank of America API beginning in early 2026 and must eventually be migrated to avoid entering an `ITEM_LOGIN_REQUIRED` state. The exact beginning and end dates of the migration will be announced in 2026. Bank of America Items on the new API will have a 12-month consent expiration applied. * Released Plaid's new User APIs, supporting all new integrations of Plaid Check, Multi-Item Link, and Plaid Protect. The User APIs create a single, simplified representation of a user via the `user_id` field and will be the representation used by the Plaid API going forward. Customers with existing integrations should continue to use user tokens; migration instructions will be released in 2026. See [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) for more details. ##### December 3, 2025  For Link: * Ended support for Modular Link, a specific form of Link only available in Europe. * Improved the ability of the returning user experience to recognize a returning user on the same device. For Layer: * Added support for the `SESSION_FINISHED` webhook, allowing backend detection of when a session is complete and `public_token` delivery. Added the following template improvements: * Layer template support for `required_if_supported_products`, `optional_products`, and `additional_consented_products`. * A custom preferred institutions list, allowing you to select which institutions are prioritized. * Customizing whether the SSN shown in Link is masked * The ability to set criteria to pre-select certain accounts in Link, like those with the highest balance or recent income, to encourage users to share those. (This feature is in closed beta; contact your account manager for access.) For Transactions: Released Personal Finance Categories v2 (PFCv2). PFCv2 includes both improved transaction categorization accuracy (approximately 10% improvement at the category level and 20% improvement at the subcategory level) and a new, more granular transaction schema with additional categories specifically useful for Earned Wage Access (EWA) use cases, with six additional income subcategories, six additional loan disbursement subcategories, and three additional loan repayment subcategories. Additional subcategories have also been added for bank fees. To opt in to PFCv2, existing customers should set `personal_finance_category_version` to `v2` in the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , or [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) request. Opting in to PFCv2 is required for existing customers to receive the new, more granular subcategories. To receive the PFCv2 accuracy improvements, customers do not need to opt in to PFCv2 (with the exception of a small subset of customers in the EWA industry). All new customers enabled for Transactions after December 3, 2025 will be opted in to PFCv2 by default. ##### November 12, 2025  For Identity Verification: * Added `latest_scored_protect_event` field to response objects in the Identity Verification endpoints. For Plaid Check Consumer Report: * Improved data normalization of the `employer_name` field. * If the data retrieved by Plaid for a Consumer Report shows strong signs of being inaccurate (e.g. balance history and transaction history inconsistent with each other, or transaction history contains duplicate transactions), the report generation will now fail with a `DATA_QUALITY_CHECK_FAILED` error. This is estimated to impact approximately one in one thousand report generation attempts. If you experience this error, wait at least 24 hours and then try again. * For [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , added `bank_income_source.status` and `bank_income_source.income_provider` fields. * For [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , make `income_provider` nullable. ##### November 4, 2025  * Fixed an issue in which unhealthy Items would occasionally continue to be reported as healthy and never enter the `ITEM_LOGIN_REQUIRED` state. * Delays with Chase OAuth registration have been resolved. Chase registration will now typically complete in approximately 1-2 business days for new clients. If you have received Production access and completed your Security Questionnaire over two weeks ago and do not yet have Chase access, contact your account manager or file a support ticket. For Link: * Released [iOS SDK](https://github.com/plaid/plaid-link-ios) v6.4.2, resolving a syncFinanceKit crash when running on iPad on compatibility mode. * Released [Android SDK](https://github.com/plaid/plaid-link-android) v.5.5.0, with the following improvements: made `LinkErrorCode.errorType` public, fixed bug where Layer "auto" customization for light/dark mode was always dark, and added `onLoad` callback to `Plaid.create` for detecting when Link is ready to present. * Released [React Native SDK](https://github.com/plaid/react-native-plaid-link-sdk) v12.6.1, updating the iOS SDK to v6.4.2 and improving internal logging and debugging to help diagnose customer issues more effectively. * Released [React Native SDK](https://github.com/plaid/react-native-plaid-link-sdk) v12.7.0. This version adds `onLoad` to `LinkTokenConfiguration`, fired once when Link is fully loaded and ready to present. You can use it to manage your own loading UI or defer presentation until ready. For Auth: * PNC TAN expiration, previously scheduled to begin in January 2026, has been postponed until further notice. Further updates on PNC TAN expiration are not expected until 2026. The changelog will be updated when new information is available. For Assets: * Added Account Insights to Asset Reports in Europe. Account Insights includes many fields providing detailed information on an end user's credit risk and affordability, including insights about spending activity, income, atypical transactions, minimum and negative balances, loan payment activity, and gambling activity. Account Insights is only available in Europe. US customers seeking similar information should use Plaid Check Consumer Report. For Plaid Check Consumer Report: * Added support for investments holdings and accounts in reports, such as Home Lending Report. For Identity Verification: * For Document Verification, `issue_date` is now exposed in the API where relevant; previously this information was only available via the Dashboard. For Transfer: * Partners can now use access tokens belonging to one of their end customers to call [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) , allowing them to more easily initiate transfers even if the end customer performed the initial Item creation. * PNC TAN expiration, previously scheduled to begin in January 2026, has been postponed until further notice. Further updates on PNC TAN expiration are not expected until 2026. The changelog will be updated when new information is available. ##### October 15, 2025  For Balance, Transfer, and Signal: * Renamed "Signal" product to "Signal Transaction Scores". "Plaid Signal" now refers to Plaid's suite of capabilities used for assessing ACH return risk, which includes both Signal Transaction Scores and Balance. * Streamlined Balance and Signal Transaction Scores integrations with the creation of Balance-only Signal rulesets and a single shared integration path for the Plaid Signal suite (Balance and Signal Transaction Scores) using the [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) endpoint. * Balance customers, including those who do not use Signal Transaction Scores, can now integrate using the [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) endpoint and Signal Rules in the Dashboard to take advantage of no-code configuration, managing business logic, and tuning rules. * Signal Transaction Scores customers can manage both Signal rule evaluations (now known as Signal Transaction Scores-powered rule evaluations) and Balance-only rule evaluations via a single Dashboard, consolidating business logic and performance tuning for all Plaid Signal products in a single no-code interface. * All new Signal Transaction Scores customers who do not specify a `ruleset_key` when calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) will now be assumed to be using the `default` ruleset, rather than no ruleset. Customers who do not want to use a ruleset can contact their account manager to opt out. This change does **not** impact existing Signal Transaction Scores customers; all existing customers will automatically be opted out of this behavior. These changes will automatically take effect for all new customers who are enabled in Production for Balance or Signal Transaction Scores after October 15, 2025. A migration path will be available soon for existing customers. If you are an existing customer and would like to migrate early, contact your account manager for information. For Plaid Check Consumer Report: * Released the Plaid LendScore. The LendScore is a score from 1-99 that indicates an end user's creditworthiness based on data from their Plaid-linked accounts. LendScore is currently in closed beta. To request access, existing customers should contact their Plaid account manager; new customers should contact sales. * Released Cash Flow Insights, providing aggregated transaction data across all permissioned accounts. This data can be used for credit decisioning and forms the basis of the Plaid LendScore. Cash Flow Insights is currently in closed beta. To request access, existing customers should contact their Plaid account manager; new customers should contact sales. For Transfer: * Released Transfer for Platforms (formerly Platform Payments) to wider beta for reseller partners (i.e. platforms that incorporate Plaid to facilitate pay-by-bank for their customers), with a set of redesigned endpoints for Platform use cases. If you are interested in using Transfer as a Platform, contact your Plaid account manager. ##### October 13, 2025  For Link: * Released [Android SDK](https://github.com/plaid/plaid-link-android) v5.4.0, resolving an issue in which the `selection` event was missing in `LinkEvent.EventMetadata`, resolving an issue where `metadataJson` in `LinkEventMetadata` could be an empty string instead of `{}`, and improving internal logging and debugging to help diagnose customer issues more effectively. * Released [React Native SDK](https://github.com/plaid/react-native-plaid-link-sdk) v12.6.0, updating Android to v5.4.0 and iOS to v6.4.1. For Auth: * Enabled known Instant Match incompatible depository accounts within the single account Account Select pane. While these accounts cannot be connected via Instant Match, end users can now select them in order to verify them via other methods, such as micro-deposits or Database Auth. For Plaid Check Consumer Report: * Base Reports and Income Insights Reports are now available to customers on Pay-as-you-go or Growth plans. For Partners: * Partners can now file tickets on behalf of their end customers directly from the Partner Dashboard without impersonating the end customer. This feature is not yet available for missing/faulty data categories. ##### October 1, 2025  For Link: * Released [iOS SDK](https://github.com/plaid/plaid-link-ios) v6.4.1, resolving an issue in which the `selection` event was missing in `LinkEvent.EventMetadata` and improving internal logging and debugging to help diagnose customer issues more effectively. For Auth and Identity: * Released UI improvements to the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) , including labels and session counts on the Overview page to show at a glance which flows each Link customization is enabled for and which customizations are actively used. For Credit products: * Released UI improvements to the Credit Dashboard (beta), including improved search, sort, and filter capabilities on the session overview page; breadcrumb navigation within the Dashboard; labeling of pending versus posted transactions; and color-coding / formatting to more clearly distinguish positive from negative transaction amounts. For Layer: * Shipped UI changes to the Layer flow to increase conversion. For Transfer: * Changed the default and maximum `count` values for [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) from 25 and 100 to 100 and 500, respectively. ##### September 24, 2025  Due to a change in Chase's permissioning UI, the `USER_ACCOUNT_REVOKED` webhook will no longer be fired for Chase Items, as Chase no longer allows account-level permissions revocation. Instead, the `USER_PERMISSION_REVOKED` webhook will be fired. PNC Items will continue to support the `USER_ACCOUNT_REVOKED` webhook. For Plaid Check Consumer Report: * Updated designs of certain panes in the Link flow. These are small visual updates that have resulted in improvements to both Link conversion and Plaid Passport enrollment. For Transfer: * Deprecated the `funds_settlement_date` field. All customers using Plaid Ledgers should use the `expected_funds_available_date` instead. ##### September 16, 2025  For Link: * Released [React Native SDK](https://github.com/plaid/react-native-plaid-link-sdk) v12.5.1, containing bug fixes for Android build errors. * Released [React Native SDK](https://github.com/plaid/react-native-plaid-link-sdk) v12.5.2, resolving iOS startup crash on React Native version 0.81+ introduced in v12.5.1. Also adds `metadataJson` key to event data to allow for all keys to be camelCase and updates Android SDK to 5.3.3. * Released [React Native SDK](https://github.com/plaid/react-native-plaid-link-sdk) v12.5.3, upgrading Android SDK to v5.3.4. * Released [Android SDK v5.3.3](https://github.com/plaid/plaid-link-android) , containing the following changes: upgrade dependency `com.google.code.gson:gson` to 2.9.1, upgrade dependency `com.squareup.okhttp3:logging-interceptor` to 4.9.2. * Released [Android SDK v5.3.4](https://github.com/plaid/plaid-link-android) , fixing a retrofit reinitialization bug. For Auth: * TAN expirations at PNC have been postponed until January 2026. While PNC Items will still expire after one year if consent is not renewed, the TAN will continue to be valid until at least January 2026. For Plaid Check Consumer Report: * For Cashflow Monitoring, added the ability to subscribe to updates on a per-Item level. * For Cashflow Monitoring, removed the fields `baseline_count` and `baseline_amount` in response to customer feedback. These fields will be omitted or returned with `null` values going forward. For Identity Verification: * Improvements to Trust Index Scores (US verifications only): * Added the Trust Index Thresholds feature, which allows customers to set a minimum Trust Index score in addition to attribute-based Risk Rules. * Improved and simplified the UI for displaying Trust Index Scores. Identity Verification will now display the primary drivers for the score as bullet points. * Improved the algorithm for calculating Trust Index Scores, resulting in substantially increased accuracy. ##### August 28, 2025  For Investments Move: * Added a new error code, `MANUAL_VERIFICATION_REQUIRED`, when [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) is called on an Item that requires an interactive Link session for verification. To resolve this error, send the Item through update mode. ##### August 27, 2025  For the Dashboard: * The "Team Management" permission is no longer required to access the Link Analytics page. Any verified user can now access this page. * The "Link Customization Write Access" permission is now required to access Link Customization / Template editor pages instead of the "Team Management" permission. For Link: * Released [Plaid Android SDK 5.3.2](https://github.com/plaid/plaid-link-android/) , including an upgrade to version 3.25.5 of the `com.google.protobuf:protobuf-kotlin-lite` library. For Auth: * Improved the Link UI on the "Are you sure?" screen displayed when an end user attempts to close Link without connecting an account. The new screen more prominently displays the option to link an account via non-credential based flows (if enabled), resulting in increased Link conversion. For Plaid Check Consumer Report: * Added support for Consumer Report in the [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) Link UI. This Link configuration is recommended when using Consumer Report alongside Auth as part of a single Link flow that supports bank account linking for both underwriting and repayment. For Layer: * Added [Extended Autofill](https://plaid.com/docs/layer/index.html.md#extended-autofill) , which expands the number of users who can have their personal information prefilled with Layer, even if their phone number is not Layer eligible. To learn more and add Extended Autofill to your existing integration, see [Extended Autofill](https://plaid.com/docs/layer/index.html.md#extended-autofill) . For Transfer: * Added monthly Transfer reconciliation report emails. This feature is currently opt-in; to request access, contact your Plaid account manager. ##### August 17, 2025  For the Plaid Dashboard: * Added audit logs of Dashboard actions. Audit logs are available to admins via the Dashboard under Settings -> Audit Logs. Currently, core Dashboard actions are logged; logging for actions in product-specific Dashboards is not yet available. Audit logs are available only to customers on Premium Platform Support packages. To learn more about upgrading to a Premium Platform Support package, contact your account manager. For all products: * For [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) , added optional `reason_code` and `reason_note` fields. Using these fields when removing an Item can help Plaid identify fraud and bad actors in the Plaid Network, improving anti-fraud data for all Plaid customers. For Plaid Link: * Released [Plaid Android SDK 5.3.1](https://github.com/plaid/plaid-link-android/) , fixing a bug in which screens did not properly resize for the keyboard on Android 15+. For Plaid Check Consumer Report: * Added the ability to generate Home Lending Report and Employment Refresh reports suitable for providing to GSEs. To generate these reports, use the `base_report.gse_options` field when calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) or [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . * Added the ability to create and manage OAuth tokens to securely share consumer report data with Plaid partners Experian, Fannie Mae, and Freddie Mac. For more details, see [Consumer Report OAuth data sharing](https://plaid.com/docs/check/oauth-sharing/index.html.md) . For Identity Verification: * In the Document Verification `analysis` object, added the `aamva_verification` object to report results from the American Association of Motor Vehicles Administrators (AAMVA) Drivers License Data Verification service. This object is currently in beta. To receive AAMVA data, you must enable the corresponding feature in your Identity Verification template under the "DMV/Secretary of State Validation" header in the Workflow tab of the Template Editor. This object will only be populated for US drivers licenses in [participating states](https://www.aamva.org/it-systems-participation-map?id=594) . For Investments: * Removed the `sedol` field from responses, as this field was only available for stocks that trade on London Stock Exchange and to customers that had the appropriate licenses. The `sedol` field will now be `null` for all securities. * Added `subtype` identifiers to the `security` object to specify the type of a security in more detail. New subtype values are: `asset backed security`, `bill`, `bond`, `bond with warrants`, `cash`, `cash management bill`, `common stock`, `convertible bond`, `convertible equity`, `cryptocurrency`, `depositary receipt`, `depositary receipt on debt`, `etf`, `float rating note`, `fund of funds`, `hedge fund`, `limited partnership unit`, `medium term note`, `money market debt`, `mortgage backed security`, `municipal bond`, `mutual fund`, `note`, `option`, `other`, `preferred convertible`, `preferred equity`, `private equity fund`, `real estate investment trust`, `structured equity product`, `treasury inflation protected securities`, `unit`, `warrant`. For Transfer: * In the [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) response `rfp` object, added `max_amount` and `iso_currency_code` fields. * Added [/transfer/ledger/event/list](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgereventlist) endpoint. ##### August 6, 2025  For Plaid Link: * Released a visual refresh of the Link UI to match the Plaid brand refresh. This update does not change the functionality of Link. * Released [Plaid iOS SDK 6.4.0](https://github.com/plaid/plaid-link-ios) , adding `issueDescription` and `issueDetectedAt` to `EventMetadata`. * Released [Plaid Android SDK 5.3.0](https://github.com/plaid/plaid-link-ios) , adding `issueDescription` and `issueDetectedAt` to `EventMetadata`, the event `LAYER_AUTOFILL_NOT_AVAILABLE`, and supporting the `dateOfBirth` parameter for Layer. * Released [Plaid React Native SDK 12.4.0](https://github.com/plaid/react-native-plaid-link-sdk) . This release updates the Android SDK to 5.3.0 and the iOS SDK to 6.4.0. It also includes updates to the example application to make it more clear how to use Layer and Sync Financekit. * Released [Plaid React Link SDK 4.1.1](https://github.com/plaid/react-plaid-link) , patching a build issue introduced in version 4.1.0. For Plaid Check Consumer Report: * Improved income forecasting calculations in the Income Insights report: * Tax refunds and inactive income streams will no longer contribute to forecasted income. * Income forecasts will now use all available income history (up to 5 years) rather than a 90 day maximum. * During the week of August 18, 2025, Data Transparency Messaging (DTM) will be disabled for Consumer Report until further notice. No action is needed on the part of impacted customers. For Link sessions that include both Plaid Check products and Plaid Inc. products in a single Link flow, DTM will still be used for Plaid Inc. products if it is otherwise enabled for the Link flow. For Signal: * Beginning September 1, 2025, when [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) or [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) is called with an unknown `client_transaction_id` (one that was never submitted to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) ), these endpoints will return an error instead of a success response. This change better reflects that these endpoints should only be used to report returns or decisions on previously-evaluated transactions. For Transfer: * Added more granular Transfer-specific permissions controls to the Dashboard. For more details, see [Transfer Dashboard permissions](https://plaid.com/docs/transfer/dashboard/index.html.md#dashboard-permissions) . To manage your team's Transfer permissions, use the [Dashboard -> Team Settings -> Members page](https://dashboard.plaid.com/settings/team/members) . ##### August 4, 2025  For Plaid Link: * Released [Plaid React Link SDK 4.1](https://github.com/plaid/react-plaid-link) , with support for passing date of birth for Layer autofill. ##### July 30, 2025  For Plaid Link: * Released [Plaid iOS SDK 6.3.2](https://github.com/plaid/plaid-link-ios) , with fixes to XCFramework signing issue. * Released [Plaid iOS SDK 6.3.1](https://github.com/plaid/plaid-link-ios) , with updated Layer Submit API, new Layer event `LAYER_AUTOFILL_NOT_AVAILABLE`, and exposing Finance Kit sync simulated behavior to Objective-C (React Native). * Released [Plaid React Native SDK 12.3.2](https://github.com/plaid/react-native-plaid-link-sdk) , updating the React Native SDK to use Plaid iOS SDK 6.3.2. * Released [Plaid React Native SDK 12.3.1](https://github.com/plaid/react-native-plaid-link-sdk) , updating the React Native SDK to use Plaid iOS SDK 6.3.1. ##### July 25, 2025  For Plaid Link: * Released [Plaid Android SDK 5.2](https://github.com/plaid/plaid-link-android/) , with new event names and a new event metadata field, improved behavior for `destroy()`, a smaller SDK size, and removal of unused dependencies. For more details, see the [release notes](https://github.com/plaid/plaid-link-android/releases/tag/v5.2.0) * Released [Plaid React Native SDK 12.3.0](https://github.com/plaid/react-native-plaid-link-sdk) , updating the React Native SDK to use Plaid Android SDK 5.2 and Plaid iOS SDK 6.3. * Began rolling out a progress bar in the Link UI to all customers. During testing, Link sessions with the progress bar displayed showed a statistically significant increase in Link conversion. ##### July 24, 2025  For the Plaid Dashboard: * Improved the user experience for OAuth registration and onboarding: * OAuth registration status is now displayed more prominently within the Dashboard * Added estimated timelines for institution enablement * Accelerated the OAuth registration process, resulting in shorter waits for OAuth enablement * Added more complete list of institutions that use OAuth and their enablement statuses * Added detailed and actionable error messages if an error occurred during registration * Customers on Growth or Custom plans will automatically be enabled for access to Charles Schwab; customers on Pay-as-you-go plans will still need to explicitly request Schwab access * Added the ability to export the list of team members to CSV. * Added the ability for customers with Premium Platform Support Packages to self-serve enable SCIM in the Dashboard without contacting Plaid support or their account manager. * Removed Data Quality related Known Issues the Dashboard, as these issues were often described in vague terms, causing customers to think they were encountering a known issue when they were not. Removing these from the Known Issues section of the Dashboard helps Plaid more accurately identify data quality issues and reduces customer confusion caused by following the wrong Known Issue. Connectivity-related Known Issues are still reported in the Dashboard. * When users attempt a Dashboard action they don't have permissions for, they will now be shown a list of admins whom they can contact to request permission. For Plaid Link: * Released [React Native Plaid Link SDK 12.2.1](https://github.com/plaid/react-native-plaid-link-sdk) , with bug fix for the error message "PLKEnvironmentDevelopment not defined". * Released [Plaid iOS SDK 6.3](https://github.com/plaid/plaid-link-ios/) , with new event names and a new event metadata field, enhancements for the SwiftUI API, and improved FinanceKit testing capabilities. For more details, see the [release notes](https://github.com/plaid/plaid-link-ios/releases/tag/6.3.0) . For Plaid Check Consumer Reports: * Added support for Home Lending Report and Employment Refresh for mortgage lenders via [/cra/check\_report/verification/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationget) . This feature is in early availability; contact sales or your account manager to learn more. * Improved the accuracy of insufficient funds (NSF) transaction calculations, leading to fewer transactions being reported under the `nsf_overdraft_transactions_count` fields. * For Income Insights, improved the accuracy of income categorization, forecasted income, and historical income. * Added institution details (`institution_name` and `institution_id`) to [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) response. * Added `require_identity` boolean to options object in [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) requests. If set to `true` and user identity data is not available, CRA report creation will fail, and you will not be charged. * Updated and made consistent maximum values `days_required` and `days_requested` when generating a CRA report across multiple endpoints. The maximum value for `days_requested` is now 731 and the maximum value for `days_required` is 184. * For Partner Insights, added `client_report_id` to partner insights response. For Investments: * Improvements and bug fixes to holdings valuations, such as better reflecting the value of unvested shares. For Payment Initiation: * Added `error` field to responses of [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) and [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) containing error details when the payment fails. * Added support for cursors to [/payment\_initiation/recipient/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientlist) . * Added error field to `WALLET_TRANSACTION_STATUS_UPDATE` webhook and to responses of [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) and [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) . For Transactions: * Added [/sandbox/transactions/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransactionscreate) endpoint, which can be used to add custom transactions to the `user_transactions_dynamic` Sandbox test user. * Added the `user_ewa_user`, `user_yuppie`, and `user_small_business` Sandbox test users for persona-based testing of realistic Transactions data. * Added `account_numbers` field to `counterparty` object. For Transfer: * Added `wire_return_fee` to transfer and transfer event objects. ##### June 12, 2025  * Released [Plaid Protect](https://plaid.com/docs/protect/index.html.md) , Plaid's new anti-fraud solution. * Released [Premium Link Analytics](https://plaid.com/docs/link/measuring-conversion/index.html.md#premium-link-analytics) , a new Dashboard feature with advanced analytics insights on Link usage and conversion. Premium Link Analytics is available at no extra charge to all customers with Premium Support Packages. To learn more about upgrading to a Premium Support Package, contact your account manager. * Launched Plaid's AI Toolkit, including the Dashboard MCP Server, Sandbox MCP Server, LLM-friendly documentation, and vibe coding guides. For more details, see the [Resources page](https://plaid.com/docs/resources/index.html.md#ai-developer-toolkit) . * Released version 5.1.1 of the [Plaid Android Link SDK](https://github.com/plaid/plaid-link-android) and version 6.2.1 of the [iOS Link SDK](https://github.com/plaid/plaid-link-ios) . These updates both contain the ability to detect usage of [Plaid Link for Flutter](https://github.com/jorgefspereira/plaid_flutter) , allowing Plaid to better troubleshoot integration issues by distinguishing between Flutter and non-Flutter usage. ##### June 9, 2025  For Link: * Released version 5.1.0 of the [Plaid Android Link SDK](https://github.com/plaid/plaid-link-android) . Improvements include a bug fix for edge-to-edge layout overlap issue on Android 15+, 20% smaller SDK size, and removal of the `org.bouncycastle:bcpkix-jdk15to18` dependency. * Began rolling out a new pane added to the end of the Link flows for Assets and Bank Income, prompting end users to enroll in Plaid Passport for faster credit application flows in the future. This pane occurs after the end user has successfully completed Link and therefore has no impact on Link conversion. This pane will be released to all eligible customers by the end of August. For Plaid Check Consumer Reports: * Introduced a rate limit of 100 requests per minute for all Plaid Check endpoints. For Transfer: * Plaid Transfer now supports Instant Payments (pay-ins) via request-for-payment (RfP) on the RTP network. ##### June 3, 2025  * Announced the availability of the [Plaid Dashboard MCP server](https://plaid.com/docs/resources/mcp/index.html.md) . This service allows you to access Dashboard-based services such as Link analytics data, API usage, and the Item debugger via an LLM agent. More tools and the ability to use additional platforms will be added soon. * Released Plaid Link [iOS SDK 6.2.0](https://github.com/plaid/plaid-link-ios/releases/tag/6.2.0) . This version features a 33% smaller package size, a `showGradientBackground` option for customizing Link appearance, and a new `onLoad` callback from `Plaid.create` to help detect when Plaid is ready to present. For Auth: * Released [Account Verification Analytics](https://dashboard.plaid.com/account-verification/analytics) , Dashboard-based reports of Auth and Identity Match activity showing usage levels and conversion metrics by Auth method. For Plaid Check Consumer Reports: * For [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , deprecated `report.items.accounts.account_insights` in favor of the [attributes field](https://plaid.com/docs/api/products/check/index.html.md#cra-check_report-base_report-get-response-report-attributes) , which aggregates insights across accounts. * Announced the availability of a new model version (v4) for their scores that are provided in Partner Insights. Starting on June 2, 2025, customers using Partner Insights can choose to use the latest version when calculating the scores by specifying it in the `prism_versions` object when calling [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) . If no version is specified, Plaid will default to the current version (v3) available now. Starting in November 2025, customers will be required to specify a `prism_version` when calling Partner Insights endpoints. For Transfer: * Added [automatic Sandbox simulations](https://plaid.com/docs/transfer/sandbox/index.html.md#automatic-sandbox-simulations) , allowing you to create test transactions in Sandbox that will automatically move through the transfer lifecycle, without requiring you to manually progress them to the next state. ##### May 20, 2025  For Enrich: * Removed the legacy `category_id` and `category` fields for all customers enabled for the Transactions product on or after May 5, 2025. Customers should use the `personal_finance_category` field instead. For Transactions: * Removed the legacy `category_id` and `category` fields for all customers enabled for the Transactions product on or after May 5, 2025. Customers should use the `personal_finance_category` field instead. ##### May 14, 2025  For Auth: * Announced PNC's new TAN expiration policy. All PNC Items with TANs will require the user to have authorized or re-authorized consent within the past 12 months. If the user has not done so, the TAN will stop working and the Item will enter an `ITEM_LOGIN_REQUIRED` state. For more details, see [PNC TAN expiration](https://plaid.com/docs/auth/index.html.md#pnc-tan-expiration) . For Layer: * Added `android_package_name` to [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) . For Plaid Check Consumer Reports: * Updated `average_inflow_amount` field to be positive. For Transfer: * Announced PNC's new TAN expiration policy. All PNC Items with TANs will require the user to have authorized or re-authorized consent within the past 12 months. If the user has not done so, the TAN will stop working and the Item will enter an `ITEM_LOGIN_REQUIRED` state. For more details, see [PNC TAN expiration](https://plaid.com/docs/auth/index.html.md#pnc-tan-expiration) . ##### May 5, 2025  * Announced new `INSTITUTION_RATE_LIMIT` error and behavior for when an institution is experiencing excessive API traffic to real-time endpoints. This error will be rolled out to all customers by the end of May 2025. For Transfer: * Added `expected_funds_available_date` to the Transfer object. ##### April 24, 2025  * Released a new [migrations page](https://dashboard.plaid.com/activity/status/migrations) on the Dashboard, showing all institutions with planned or ongoing migrations to OAuth. Drilling in to each institution, you can now view the migration timeline and impact to existing Items. * Added support for Austria and Finland. For details of supported institutions and products, see [European bank coverage](https://plaid.com/docs/institutions/europe/index.html.md) . * Added `USER_PERMISSION_REVOKED` webhook support for American Express. For Layer: * Added the ability to configure Layer sessions in the Dashboard. * In [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) , moved the `user_id` field into the `user` object. * Released React Native SDK 12.1.1, with a new `destroy()` method to support Layer. For Link: * Released React Native SDK 12.1.1, with a new `destroy()` method to support Plaid Layer. * Released React SDK 4.0.1, with support for React 19. * Webview-based integration modes are no longer allowed for new customers. All new customers using mobile webview-based apps should use the Hosted Link integration mode if they can't use Plaid's SDKs. Existing customers using webview integration modes are not currently impacted. * Announced a combined phone number and consent pane for the [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) , to be rolled out to all customers in May. This change increases conversion by reducing the number of screens the end user has to complete. It does not require any integration work on your part to adopt. Both the `CONSENT` and `SUBMIT_PHONE` `TRANSITION_VIEW` Link analytics events will fire when this screen is reached. For Plaid Check Consumer Reports: * Expanded support for Silent Network Authentication (SNA), a secure, lower friction way to verify a user's phone number using their mobile network carrier. Once eligible users submit their phone number, they will see a loading pane in Link in lieu of the OTP pane. If SNA cannot verify a user's phone number, then it will fall back to OTP for verification. SNA is available for Plaid Check Consumer Reports on both iOS and Android and is compatible with T-Mobile, Verizon, and AT&T. SNA will be rolled out to all eligible Consumer Report sessions by the end of May. No work is required on your part to support SNA. SNA is supported on Android SDK versions >=5.6.0 and iOS SDK versions >=4.7.9. To get the latest performance improvements for SNA, it is strongly recommended that all Plaid Check customers using Plaid's mobile SDKs upgrade to iOS SDK >=6.0.1 (or React Native iOS >=12.0.2). * Date of birth is now required within the consumer report user identity object for [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) . * Added `warnings` to responses for [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , [/cra/check\_report/network\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportnetwork_insightsget) and [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) . `warnings` is populated when Plaid successfully generated a report, but encountered an error when extracting data from one or more Items. * A user's phone number can now be pre-filled in Link using data from the `consumer_report_user_identity` object if the phone number is not pre-filled via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . * A new toggle on the last pane of the Link flow enables users to opt-in to a faster way to share their consumer reports in the future. * Updated the list of [Cash flow updates webhooks (beta)](https://plaid.com/docs/api/products/check/index.html.md) . For Signal: * Added `triggered_rule_details` to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) response. For Transactions: * Updated the response schema for [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) endpoint to allow `null` account objects. This change only impacts Transactions processor partners. ##### March 31, 2025  For Identity Verification: * Announced the rollout of Age Estimation and Biometric Deduplication features. On May 1, 2025, Plaid will backfill historical ID document and liveness data and enable these features for all customers using IDV templates with ID document and/or liveness enabled, free of charge. Any Plaid customer who wants to opt out of this functionality should contact their account manager. ##### March 25, 2025  * Added a "copy link" button to the Team switcher page in the Dashboard, allowing Dashboard users to access a persistent link to their team. For Assets: * To minimize data access, Assets no longer requests the Investments data scope by default. To use the Investments add-on, `investments` must now be specified in the `optional_products` array when initializing Link. For Layer: * Added the [LAYER\_AUTHENTICATION\_PASSED webhook](https://plaid.com/docs/api/products/layer/index.html.md#layer_authentication_passed) . For Investments: * Added Vanguard access via OAuth. Access to Vanguard is no longer restricted during peak market hours. For Plaid Check Consumer Reports: * Broke up the existing `DATA_UNAVAILABLE` error into more specific error codes when possible, introducing the new codes `INSTITUTION_TRANSACTION_HISTORY_NOT_SUPPORTED`, `INSUFFICIENT_TRANSACTION_DATA`, and `DATA_QUALITY_CHECK_FAILED`. Also replaced `INVALID_FIELD` with `NETWORK_CONSENT_REQUIRED` for the use case where the end user has not given consent to share network data. For details on these new codes, as well as improved documentation of existing codes, see [Check Report Errors](https://plaid.com/docs/errors/check-report/index.html.md) . * Improved the sensitivity of the `CHECK_REPORT_FAILED` webhook at alerting to partial failures. Previously, certain types of partial Check Report failures would not trigger the webhook. * Added `successful_products` and `failed_products` arrays to the `CHECK_REPORT_READY` webhook to provide more granular detail on partial Check Report failures. * Plaid can now pre-fill a user's phone number in Link using information from the `consumer_report_user_identity` object if the phone number is not pre-filled via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Pre-filling phone numbers can help boost conversion while reducing steps for users. Support for this feature is currently available in Production and will be added in Sandbox in the coming months. * Increased the speed of report generation by approximately 25%. * By the end of March, to improve security, Plaid will send all end users who complete the Plaid Check Link flow flow a confirmation email, similar to the change to Plaid Link announced in the [January 30 changelog entry](https://plaid.com/docs/changelog/index.html.md#january-30-2025) . For Signal: * Added real-time backtesting support to the Signal Dashboard. * Added a view-only permission to the Signal Dashboard. ##### March 17, 2025  For Link: * Released iOS SDK 6.1.0, with improvements to Remember Me Silent Network Authentication. * Released React Native SDK 12.0.3, which updates to iOS SDK 6.1.0. For Auth and Transfer: * Announced the impending migration of US Bank to tokenized account numbers (TANs), scheduled to occur May 2025. For Identity: * Added support for API-based detection of pass / fail results from Identity Match sessions when Identity Match rules are configured via the [Dashboard](https://dashboard.plaid.com/account-verification) via the `IDENTITY_MATCH_PASSED` and `IDENTITY_MATCH_FAILED` Link events. For Layer: * Publicly documented [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) as the preferred endpoint for creating a Layer session, rather than [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , and added `redirect_uri` support to [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) . For Plaid Check Consumer Reports: * Added support for `client_report_id` to Income Insights Reports. Moved `client_report_id` field to the top-level [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) request, rather than being inside the `base_report` request object, to reflect that the `client_report_id` is no longer Base Report-specific. Usage of the `client_report_id` within the `base_report` object is deprecated. * Changed the `score` field from a float to an integer in the API spec, to reflect that it will always be an integer. For Statements: * Added `posted_date` field to [/statements/list](https://plaid.com/docs/api/products/statements/index.html.md#statementslist) response. ##### March 1, 2025  For Auth: * Added the ability to configure micro-deposit and database verification-based Auth flows via the [Dashboard](https://dashboard.plaid.com/account-verification) . * Marked Database Match and Database Insights (beta) as deprecated in favor of the new Database Auth feature, which provides functionality similar to Database Insights. These features are still available, but customers should plan to migrate to Database Auth when possible. For Identity: * Added the ability to configure Identity Match rules via the [Dashboard](https://dashboard.plaid.com/account-verification) when using Identity and Auth as the only products. For Plaid Check Consumer Report: * Updated behavior when calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) to improve consistency. Previously, no reports would be eagerly generated upon calling this endpoint. Now, the base report will always be eagerly generated, along with products specified in the `products` array. * When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , it is now possible to include Plaid Check products within the `optional_products`, `required_if_supported_products`, or `additional_consented_products` request fields when Plaid Inc. products are included in the `products` field, or vice-versa. * Identity data is now provided in the Base Report only. Plaid will no longer return identity data in the Income and Partner Insights products, and the fields will be removed from API responses by June 30, 2025. * Removed the Cashflow Updates `INSIGHTS_UPDATED` `reason` code. Instead, a separate webhook will be fired for each reason. * The `score` field in [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) is now nullable. For Transfer: * Added `intent_id` to the transfer event object returned by [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) , for transfers created via Transfer UI. This will currently only be populated for RfP transfers. ##### February 11, 2025  For Link: * Released React Native SDK 12.0.3, which contains LinkKit 6.0.4, which fixes an issue where some sessions experienced delays in receiving the `LAYER_READY` event or did not receive it at all, and fixes an issue with XCFramework. For Auth: * Improved Sandbox behavior to better reflect institutions that use Tokenized Account Numbers (TANs). In Sandbox, Chase and PNC will now return `is_tokenized_account_number: true` and have populated `persistent_account_id` fields. For Plaid Check Consumer Report: * `consumer_report_user_identity.date_of_birth` is now a required field when creating or updating a user token with a `consumer_report_identity` field. * Completed the renaming of several fields. The `longest_gap_between_transactions`, `average_inflow_amount`, and `average_outflow_amount` fields have been removed and replaced with pluralized versions `longest_gaps_between_transactions`, `average_inflow_amounts`, and `average_outflow_amounts` fields to better reflect the fact that they are arrays. For Signal: * Announced a behavior change for Items that were manually linked (e.g. using Same Day Micro-deposits or Database Insights). Beginning February 18, any Item that was manually linked but could not be given a Signal score and attributes by [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) will no longer return a `PRODUCT_NOT_SUPPORTED` error. Instead, the [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) call will succeed. This change allows customers to evaluate these Items using Signal Rules that do not require a Signal score and attributes. Billing will only be triggered for the [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) call if either a score is returned or a Signal Rule is evaluated. For Virtual Accounts: * Added `originating_fund_source` to [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) request. This field is required by local regulation for certain use cases (e.g. money remittance) to send payouts to recipients in the EU and UK. ##### February 3, 2025  For Link: * Released iOS SDK 6.0.4, which fixes an issue where some sessions experienced delays in receiving the `LAYER_READY` event or did not receive it at all, and fixes an issue with XCFramework. ##### January 30, 2025  Notified all customers that they must sign an addendum to their agreement with Plaid to retain PNC data access after February 28th, 2025. If you do not know how to sign this addendum, or are not sure if you have signed it, contact your Plaid account manager or Plaid support. For Link: * Released React Native SDK 12.0.1, which includes iOS SDK 6.0.2 and resolves issues where the SDK was not working with React Native 0.76 or later. * Released React Native SDK 12.0.2, which results an issue where the `USE_FRAMEWORKS` preprocessor check was failing for projects using `use_frameworks! :linkage => :static`. * To improve anti-fraud measures, began more broadly sending email confirmations to end users when they have linked an account to Plaid, allowing them to report unrecognized Link activity. Previously, Plaid would send these notifications only if the session was flagged as elevated risk. For Payment Initiation (UK/EU): * Added the `end_to_end_id` field to the payment object, providing a unique identifier for tracking and reconciliation purposes. For Transfer: * For [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) , added an `institution_supported_networks.rfp.debit` field to indicate an institution's support for debit request for payment (RfP). * Added `funds_available` sweep status and event type. ##### January 17, 2025  SSO is now available, at no additional charge, to all customers except those on Pay-as-you-go plans. You can enable SSO via the [Dashboard > Team Settings > SSO](https://dashboard.plaid.com/settings/team/sso) . For Link: * Released iOS SDK 6.0.1, with enhanced support for Silent Network Authentication in the Remember Me flow. * Released iOS SDK 6.0.2, with small improvements to the UI of the Remember Me flow. * Improved the UI for failed connection attempts at OAuth institutions to increase conversion. Rather than "Exit," the primary CTA on the Link error screen for this scenario is now a "Try Again" button that will directly re-start the institution's OAuth flow. * Added phone number recycling detection to Link. The returning user experience will delete a user's Returning User profile if it detects that the phone number has been reassigned to a different customer since the user's last login, reducing the risk of fraud and account takeover. For Plaid Check: * Added `nsf_overdraft_transactions_count_30d/60d/90d` fields to `attributes` field of [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) . For Payment Initiation: * Added [/sandbox/payment/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpaymentsimulate) endpoint to improve ease of testing in Sandbox. For Signal: * [Signal Rules](https://plaid.com/docs/signal/signal-rules/index.html.md) now supports creating rules based on the results of a [Database Insights](https://plaid.com/docs/auth/coverage/database/index.html.md) check. For Transfer: * Added Transfer Rules, allowing you to customize the logic used by the Transfer Risk Engine during the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) call. You can configure your [Transfer Rules](https://dashboard.plaid.com/transfer/risk-profiles) via the Dashboard. * To better represent errors from a variety of payments rails beyond just ACH, added `failure_code` and `description` fields to [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) and `transfer/sweep/list` endpoints. Developers should use these instead of the `ach_return_code` field. ##### January 2, 2025  For Link: * For institutions such as PNC, Chase, and Charles Schwab that previously invalidated Items when a duplicate Item was added, prevented the old Item from becoming invalidated unless either Item is initialized with a Plaid Check product or the two Items have different sets of accounts associated. This is a delayed announcement of a change made in April 2024. * Released React Native SDK 12.0.0. This incorporates iOS SDK 6.0.0 and Android SDK 5.0.0. Major updates include adding support for FinanceKit and AppleCard on iOS, removing the deprecated `PlaidLink` component and `openLink` function, and updating a number of Android libraries. For a full list of all changes in this release, see the [Release notes](https://github.com/plaid/react-native-plaid-link-sdk/releases/tag/v12.0.0) . ##### December 23, 2024  For Link: * Released Android SDK 5.0.0, containing numerous library and platform updates, including upgrading Kotlin to 1.9.25, and upgrading the compile version to SDK 35. This SDK version also adds the `AUTO_SUBMIT` event name and `INVALID_UPDATE_USERNAME` Item error, removing the `PROFILE_ELIGIBILITY_CHECK_ERROR` event name. For a full list of all libraries updated in this SDK release, see the [Release notes](https://github.com/plaid/plaid-link-android/releases/tag/v5.0.0) . ##### December 17, 2024  For Auth: * PNC now supports the `USER_ACCOUNT_REVOKED` and `USER_PERMISSION_REVOKED` webhooks, allowing you to reduce return risk. Upon receiving either of these webhooks, Auth customers should no longer make ACH transfers using the tokenized account numbers of the associated Items. For Transactions: * For the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint, added the ability to use an `account_id` filter. ##### December 13, 2024  For Plaid Check: * Began the rollout of Plaid Passport, an update to the Plaid Check bank linking flow. Plaid Passport is an extension of the [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) specific to Plaid Check, and will enable conversion efficiencies across all financial institutions, improved Item health, and enhanced user-centric insights. You do not need to take any action to enable Plaid Passport. ##### December 10, 2024  For Link: * Released [React Native SDK 11.13.3](https://github.com/plaid/react-native-plaid-link-sdk) , fixing a regression introduced in version 11.13.1 that caused build failures for some customers. * Completed the rollout of Passkey support for the returning user experience in Link to all eligible sessions. Passkey support increases security and provides a more streamlined experience for returning users. With Passkeys, end users on iOS devices who have previously logged in to a financial account through Link can opt in to using Face ID or Touch ID to authenticate to this account for subsequent Link sessions. To enable Passkey support, ensure you are using the Plaid iOS SDK 4.3.0 or later or the Plaid React Native SDK 10.2.0 or later. You do not need to take any other action to enable Passkey support. ##### December 4, 2024  * Added `institution_name` to the `Item` object schema. You no longer have to call [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) to translate the institution data in an Item to human-readable format. * For [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) , added support for `USER_PERMISSION_REVOKED` and `USER_ACCOUNT_REVOKED` webhooks. For Link: * Increased the rollout of Passkey support for the returning user experience in Link. Passkey support increases security and provides a more streamlined experience for returning users. With Passkeys, end users on iOS devices who have previously logged in to a financial account through Link can opt in to using Face ID or Touch ID to authenticate to this account for subsequent Link sessions. Passkey support will be rolled out to all eligible sessions by the end of the year. To enable Passkey support, ensure you are using the Plaid iOS SDK 4.3.0 or later or the Plaid React Native SDK 10.2.0 or later. You do not need to take any other action to enable Passkey support. * Added biometric authentication support for Citibank on Android (biometric authentication support for Citibank on iOS was added in June 2024). No SDK update is required. * Released Plaid Link for React Native SDK 11.13.2, updating Android Compile Version from 31 to 34. For Auth: * Added `is_tokenized_account_number` field to [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) to indicate whether an account number is tokenized. Tokenized account numbers may require special business logic to avoid ACH returns. For more details, see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) . * Added support for cash management account subtypes, rather than just checking and savings. * Added `auth_method` enum to the `Item` object schema to indicate which verification method (e.g. Instant Auth, Same-Day Micro-deposits, Database Match...) was used to verify the Item. * Added `SAME_DAY_MICRODEPOSIT_AUTHORIZED` and `INSTANT_MICRODEPOSIT_AUTHORIZED` transition view names to Link. For Plaid Check Consumer Reports: * Added the [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) endpoint to facilitate testing. * Enhanced the model used for estimating gross income from net income, resulting in ~10% greater accuracy. * Users with the Team Management permission can now download a copy of their submitted Plaid Check application form from the Dashboard under Settings > Compliance Center > Company Documents. For Identity Verification: * At the start of the Selfie Check flow, added a warning to users if insufficient ambient light is detected, prompting them to fix their lighting conditions before proceeding. For Investments: * For the `security` object, added the `fixed_income` object with the following details: `yield_rate`, `maturity_date`, `issue_date`, and `face_value` fields, to provide additional details on bonds and other fixed income securities. * Added processor partner support for Investments with the new [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) and [/processor/investments/holdings/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentsholdingsget) endpoints. For Transfer: * Added support for cash management account subtypes, rather than just checking and savings. * Added `auth_method` enum to the `Item` object schema to indicate which verification method (e.g. Instant Auth, Same-Day Micro-deposits, Database Match...) was used to verify the Item. * Added `SAME_DAY_MICRODEPOSIT_AUTHORIZED` and `INSTANT_MICRODEPOSIT_AUTHORIZED` transition view names to Link. * Added `webhook` field to requests for [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) , [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) , [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) and `/sandbox/transfer/sweep/simulate`. * Added `funds_available` support for [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) . ##### November 14, 2024  * Released [/consent/events/get](https://plaid.com/docs/api/consent/index.html.md#consenteventsget) to help customers obtain consent logs for auditing purposes. * Added consent related-details to the `item` object in [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) , including `consented_data_scopes`, `consented_use_cases`, and `consent_expiration_time`, to help customers manage consent records and consent expiration. For Link: * Released Plaid Link for iOS SDK 6.0.0, introducing FinanceKit and support for Apple Card integration. * Released Plaid Link for React Native SDK 11.13.1, fixing a compiler error when using the New Architecture with Expo. For Assets: * Added a hard limit of 15,000 transactions per Asset Report, to avoid returning truncated Asset Reports. An Asset Report with more than 15,000 transactions will now trigger the error `ASSET_REPORT_GENERATION_FAILED` with an error message "asset report is too large to be generated, try again with a shorter date range". ##### November 7, 2024  For Link: * Released Plaid Link for React SDK 3.6.1, fixing an issue that can occur when unmounting the `usePlaidLink` hook before the underlying script tag is loaded. * Customers can now self-enable for [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) without contacting their account manager. To enable Hosted Link, provide a `hosted_link` object in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. The object can be empty or can include configuration parameters for Hosted Link. This change does not apply to Link Delivery, which still requires account manager enablement. ##### October 29, 2024  For Link: * Added support for Vietnamese and Hindi. * Added `AUTO_SUBMIT_PHONE` event to capture scenarios where the user's phone number is supplied in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call and the user has previously enrolled in the returning user experience, allowing Plaid to send an OTP code without prompting. * Improved conversion through improved error messaging for incorrect username / password at non-OAuth institutions. Previously, users would be taken to an error pane and required to press the back button to retry their credentials; the new UI provides inline error messages if the user's credentials are incorrect. * Fixed bug in which users could enter an error state by clicking a button while the in-progress spinner was active on a different button. * Minor improvements to consistency in font weight and styling. For Consumer Report by Plaid Check: * For the endpoint [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , added the `total_inflow_amount` and `total_outflow_amount` objects, with corresponding objects `total_inflow_amount_30d`, `total_inflow_amount_60d`, `total_inflow_amount_90d`, `total_outflow_amount_30d`, `total_outflow_amount_60d`, and `total_outflow_amount_90d`, to summarize inflows and outflows. * For Partner Insights Reports, deprecated the `version` field (which used type `number`) and replaced it with the `model_version` field (which uses type `string`), to better support the not-strictly-numerical versioning scheme used by Prism. For Identity Verification: * For the response bodies of the endpoints [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) , [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) , [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) , and [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) , added the `verify_sms` object. This object contains details about SMS verification attempts, with sub-fields such as `status`, `attempt`, `phone_number`, `delivery_attempt_count`, `solve_attempt_count`, `initially_sent_at`, `last_sent_at`, and `redacted_at`. * Restored the "Integration" button to the Dashboard. It can now be found next to the "Publish Changes" button in the upper right of the Template Editor. For Payment Initiation: * For [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) , added `payer_details` object. The fields `options.bacs` and `options.iban` have been deprecated in favor of `payer_details.numbers.bacs` and `payer_details.numbers.iban`; customers are encouraged to migrate to the new fields. For Signal: * Made the `scores` field nullable in the responses for [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) and [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) , as a pre-requisite for adding future Signal support to Items where a score cannot be calculated, such as Items added via Database Insights or Same-Day Micro-deposits. * Changed Signal billing to behave similarly to Auth and Identity if it is specified in the `optional_products` array -- customers will not be billed for Signal if it is specified in `optional_products` until [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) is called. ##### October 28, 2024  * Fully removed legacy returning user flows (Institution Boosting, Pre-Matched RUX, and Pre-Authenticated RUX) in favor of the new returning user experience. * Removed legacy returning user flow errors, `INVALID_PRODUCTS` and `PRODUCT_UNAVAILABLE`. ##### October 15, 2024  * For the `PENDING_DISCONNECT` webhook, added `INSTITUTION_TOKEN_EXPIRATION` as a `reason` code. This reason will be used if the user's access-consent on an OAuth token is about to expire. This webhook code will only be used for Items associated with institutions in the US and Canada; for Items in the UK and EU, Plaid will continue to send the `PENDING_EXPIRATION` webhook instead of the `PENDING_DISCONNECT` webhook in the event of pending OAuth access expiration. For Plaid Check Consumer Reports: * Reverted the change to historical balance data from the October 11 update. Updated the documentation to clarify the behavior and reduce customer confusion. * Added `attributes` object with fields `nsf_overdraft_transactions_count`, `is_primary_account`, and `primary_account_score` to Base Report object, to help identify primary accounts and overdraft transactions. For Payment Initiation: * For the `/payment_initiation/consent/*` endpoints, deprecated the `scopes` field in favor of the `type` field, with possible values `SWEEPING` or `COMMERCIAL`. The `scopes` field will still be honored if used, but customers are encouraged to use the new `type` field instead, and the `scopes` field will be removed in the future. ##### October 11, 2024  For Plaid Check Consumer Reports: * For [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) , added the fields `last_4_ssn` and `date_of_birth` to the `consumer_report_user_identity` object. All user tokens created after January 31, 2025 must have a `date_of_birth` populated in order to be compatible with Plaid Check Consumer Reports. * Changed the behavior of returning historical balances. Previously, Consumer Reports would always return at least 90 days of historical balance information. This caused user confusion in the case of new accounts opened less than 90 days ago, since Consumer Report would report a historical balance on the account for dates when the account did not yet exist. Now, Consumer Reports will only return historical balances up to the date of the oldest transaction found in a given account. * Released Cash Flow Updates and Network Insights to beta. For details, see [Plaid Check](https://plaid.com/docs/check/index.html.md#overview) . For Identity Verification: Introduced several updates to Identity Verification. These changes are being gradually rolled out to customers. To request to be opted in to these changes early, or to delay receiving these changes, contact your Plaid account manager. * Introduced Trust Index, a numerical scoring system rating the user on a scale of 1 to 100, with 11 sub-scores on different dimensions (e.g. email, phone, liveness), to help you understand users' relative risk across various dimensions and how different factors contribute to that risk. * An overhauled session view that helps you digest a full user's verification without scrolling. For Income: * Fixed an issue in which customers could successfully call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) for Income without specifying a `user_token`. The `user_token` field is required when using Income. ##### October 9, 2024  * Began the automatic enrollment of some customers into [Data Transparency Messaging (DTM)](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . Throughout Q4, customers serving end users in the US and Canada will be enrolled in DTM automatically if they have not already enrolled. * Announced the elimination of public key support, effective January 31, 2025. Beginning in February 2025, it will no longer be possible to launch Link sessions using a public key. This impacts only a small number of customers, as the Plaid public key has been deprecated since the introduction of Link tokens in mid-2020, and no teams created after July 2020 have been issued public keys. All customers who are still using public keys were notified of this change via email in September. For instructions on migration from public keys to Link tokens, see the [Link token migration guide](https://plaid.com/docs/link/link-token-migration-guide/index.html.md) . * Announced the full removal of legacy returning user flows (Institution Boosting, Pre-Matched RUX, and Pre-Authenticated RUX) in favor of the new returning user experience, to be completed by October 28, 2024. * Eligible customers (those with support packages) can enroll in SSO via the [Dashboard](https://dashboard.plaid.com/settings/team/sso) . If you would like to use SSO and do not have a support package, contact your Plaid account manager. * To reduce developer confusion, updated the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint to return the various results arrays and objects (`item_add_results`, `payroll_income_results`, `document_income_results,` `bank_income_results`, `cra_item_add_results`) as empty arrays (if arrays) or as null (if objects) when not present, rather than being omitted from the schema. For Link: * Improved the user experience for Remember Me verification on eligible Android devices by automatically filling in the OTP code received on the device. For Auth: * PNC now returns Tokenized Account Numbers (TANs) with behavior similar to Chase. For Balance: * Discontinued the Balance Plus beta program. Balance Plus beta will no longer accept new enrollments; customers currently in the beta program have been contacted directly with more details and next steps. For Plaid Check Consumer Report: * Released the Plaid Check Third-Party User Token to beta, allowing customers to partner with select lenders to provide their customers access to credit. If you are interested in this feature, contact sales or your Plaid account manager. * Integrated Plaid Check Consumer Reports with Layer to enable users to share cash flow insights alongside identity and bank data instantly, dramatically streamlining the loan application process. Users consent to share their consumer report in the final Layer pane. If you are interested in this feature, contact sales or your Plaid account manager. * Updated the [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) endpoint transaction history behavior for new customers. If no value is specified for the `days_requested` field, Plaid will default to requesting 365 days, and if a value under 180 is specified, Plaid will request 180 days. This change increases the quality of transaction history insights, as the more transaction history is requested, the more accurate the insights returned will be. This change impacts only customers obtaining Plaid Consumer Report Production access on or after October 1, 2024; the behavior for existing customers will not change. * In the [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) response `warnings` array, added a new possible warning code, `USER_FRAUD_ALERT`, which indicates that the user has placed a fraud alert on their Plaid Check consumer report due to suspected fraud. * For the [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) endpoint, added an `error_reason` to the response to surface Prism error codes. For Identity: * Released [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) to beta. Identity Document Upload provides document-based account ownership identity verification for Items that do not support [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) or [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , including Items connected via Same-Day Micro-deposits or Database Insights. For Identity Verification: * Redesigned the fraud labeling system UI to allow 1-click fraud reports from the Dashboard. * Fixed ordering of Link events callbacks when Hide Verification Outcome is enabled so that `IDENTITY_VERIFICATION_CLOSE_UI` fires and `onSuccess` is called after the event corresponding with the outcome of the session has fired. For Layer: * Integrated Plaid Check Consumer Reports with Layer to enable users to share cash flow insights alongside identity and bank data instantly, dramatically streamlining the loan application process. Users consent to share their consumer report in the final Layer pane. If you are interested in this feature, contact sales or your Plaid account manager. For Payment Initiation: * For [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) endpoint, added the optional `processing_mode` parameter. This allows you to opt in to async payment execution processing, allowing for better performance and throughput when real-time payment processing results are not necessary, such as in user-not-present flows. For Transfer: * Improved [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) to consider more information about accounts, such as whether the account has previously returned codes R02 (account closed) or R16 (account frozen) when used with Plaid. ##### September 2024  * Released [Link Recovery](https://plaid.com/docs/link/link-recovery/index.html.md) to beta. With Link Recovery, your end users can sign up to be automatically notified by Plaid when an institution outage that prevented them from linking an account has been resolved. When the issue is over, Plaid will send users a link that can be used to connect their account to your app. * Released [Investments Move](https://plaid.com/docs/investments-move/index.html.md) to early availability. Investments Move facilitates ACATS and ATON brokerage transfers by providing user-permissioned data including a user's account number, account information, and detailed holdings information. Investments Move can remove friction for end users in changing brokerages and reduce the frequency of transfer failures caused by data entry errors. * Improved retry logic for missed webhooks. If a webhook sent by Plaid is not accepted by the webhook receiver endpoint with a `200` status within 10 seconds of being sent, Plaid will now retry up to six times over a 24-hour period, using an exponential backoff algorithm, rather than the previous behavior of retrying up to twice, a few minutes apart. * Added a new `PENDING_DISCONNECT` Item webhook to alert customers of Items that are about to enter an unhealthy state. Unlike the existing `PENDING_EXPIRATION` webhook, `PENDING_DISCONNECT` covers Items that will break due to reasons other than consent expiration, such as a planned sunset by the bank of an old online banking platform, or a required migration to OAuth. Upon receiving a `PENDING_DISCONNECT` webhook, customers should direct the end user to the update mode flow for the Item. * Added the ability to use update mode to reauthorize consent for a US or CA Item whose consent is expiring due to 1033 rules. If the consent expiration date is within 6 months, Plaid will automatically route the Item through the longer reauthorization update mode flow, which will cause the expiration date to be pushed to 12 months from the date that the user reauthorizes the Item. You can customize whether or not the Item goes through the reauthorization update flow by using the `update.reauthorization_enabled` parameter in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Note that there is no reason to send Items through the reauthorization flow at this time, as Items will not be assigned consent expiration dates until approximately December 2024. This change only impacts Items in the US and Canada; the OAuth update flow for Items in the UK and EU has not changed. * To help manage consent status for the upcoming wider Data Transparency Messaging rollout, added `consented_use_cases`, `consented_data_scopes`, and `created_at` fields to the Item object. * Removed `deposit_switch` from the `products` array, as part of Deposit Switch deprecation. For Link flow: * Shortened and clarified text shown to end user during prompt to verify 2FA code. * Added hover animations to UI buttons in Link. For Plaid Link SDKs: * Released iOS SDK 5.6.1, which adds adds haptics support, fixes embedded search view dynamic resizing, and adds missing event names and view names. For details, see the [iOS SDK changelog](https://github.com/plaid/plaid-link-ios/releases) . * Released Android SDK 5.6.1, which adds missing event names and view names. For details, see the [Android SDK changelog](https://github.com/plaid/plaid-link-android/releases) . * Released React Native SDK 11.13.0, which incorporates iOS SDK 5.6.1 and Android SDK 4.6.1. For details, see the [React Native SDK changelog](https://github.com/plaid/react-native-plaid-link-sdk/releases) . For Assets: * Added [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) request parameter `options.require_all_items`, with a default value of `true`. By setting this to `false`, customers can optionally choose to generate an Asset Report even if one or more Items in the Asset Report encounters an error, as long as at least one Item succeeded. Otherwise, the endpoint will maintain its current behavior of only creating an Asset Report if all Items could be successfully retrieved. For Consumer Report: * Fixed confusing pluralization by renaming `longest_gap_between_transactions` to use `gaps` rather than `gap` as this field is array of gaps rather than a single gap. The old version of this field is deprecated and will be removed at the end of October. * Removed the `products` field from the [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) request, as its usage there is deprecated. For Identity Verification: * Added `liveness_check` results to [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) to improve parity between API and Dashboard data availability. * Added `name` object to the `extracted_data` within each `documentary_verification.documents` object in the response of all of the Identity Verification endpoints. * Design updates to the Identity Verification Dashboard. For Investments: * Added `sector` and `industry` fields to the securities object to help categorize holdings. For Transfer: * Updated [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) to accept either a `transfer_id` or a `transfer_authorization_id`. * In [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) request, replaced `from_client_id` and `to_client_id` with `from_ledger_id` and `to_ledger_id`. ##### August 2024  * Added [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) , which allows end users to link multiple financial accounts in a single Link session. * Added the `error_code_reason` field to the Plaid error object to provide more useful troubleshooting details for `ITEM_LOGIN_REQUIRED` errors at OAuth institutions. This field is currently in beta and may not be present for all customers. * Added the ability to launch update mode with a user token and augmented [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with an `update.item_ids` field to optionally specify which Item ID(s) to update when launching Link in update mode with a user token. Launching update mode with a user token is the only supported update mode flow for Consumer Report. For products that use both access tokens and user tokens, like Income, update mode can be launched using either one. For Plaid Link SDKs: * Released an alternative installation repo to reduce download sizes for projects using Swift Package Manager. For details, see the [iOS SDK changelog](https://github.com/plaid/plaid-link-ios/releases) . * Released Android SDK 4.6.0, with dependency updates and improved Java compatibility. For more details, see the [Android SDK changelog](https://github.com/plaid/plaid-link-android/releases) . * Released React Native 11.2.1, with enhanced support for React Native New Architecture, and including upgrades to Android SDK 4.6.0 and iOS SDK 5.6.1. For more details, see the [React Native SDK changelog](https://github.com/plaid/react-native-plaid-link-sdk/releases) . For Plaid Link: * The password input boxes in Link now allow the user to optionally reveal the password before submitting their credentials, in order to help reduce typos in password data entry. For Beacon (beta): * Added data breach reporting. For Plaid Check Consumer Reports: * Added a `consumer_disputes` field to the response for [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , showing the details of any disputes the consumer has submitted about the information in the report. For Identity Verification: * Added `is_shareable` parameter to [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) to allow configuring different retry behavior for the original session and retry sessions. If set, this parameter will control whether a shareable link is generated for the retry session. If not set, the retry session will use the same shareable link behavior as the original session. For Income: * Added `file_type` field to [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) . * Added the ability to customize the `ytd_amount` field in the Sandbox custom user for [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . For Investments: * Added Investments Refresh. Investments Refresh is available as an add-on to Investments and allows you to make a real-time, on-demand update request for fresh Investments data by calling the [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) endpoint. For Liabilities: * Plaid has discontinued support for federal student loan providers: Aidvantage, Central Research, Inc., EdFinancial Services - Federal Direct Loan Program (FDLP), Mohela and NelNet. Beginning in September, Liabilities subscriptions on Items from these institutions will no longer be billed, and end users will not be able to select these institutions in Link. Private student loan providers are not impacted. Impacted customers have been contacted directly by their account managers. For questions, contact your Plaid account manager. For Transfer: * Added support for multiple Ledgers. This improves the Plaid Transfer experience for customers who need to avoid co-mingling funds from different types of sources. As part of this change, several Transfer endpoints now have the optional ability to specify a `ledger_id` in the request and/or will return a `ledger_id` as part of the response. To request multiple Ledgers, contact your Plaid account manager. * Improved the flow for authorizations that could not be evaluated due to the `ITEM_LOGIN_REQUIRED` error by enabling [update mode](https://plaid.com/docs/link/update-mode/index.html.md) for these authorizations, allowing them to be retried after the Item is fixed. Authorizations that previously would have had an `approved` decision and a `rationale_code` of `ITEM_LOGIN_REQUIRED` will now have the new `user_action_required` decision instead. If [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) returns an `user_action_required` decision, you can now launch Link in update mode by creating a Link token with the `authorization_id` passed to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . After the end user has completed the update mode flow, you can retry the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) call. * For [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) , added an [authorization\_usage](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) response object allowing you to see your credit and debit utilization details. For Virtual Accounts: * Added the `related_transactions` array to the Wallet transaction object. This field makes it easier to identify associated transactions by showing the transaction ID of related transactions, as well as how they are related. For example, if a transaction is refunded, the original transaction and the refunded transaction will be linked via the `related_transactions` field. ##### July 2024  * Added support for Silent Network Auth (SNA) for the Android returning user experience. SNA is a faster and more secure method to verify an end user's phone number. To use SNA, you must be using at least version 3.14.3 or later of the Android SDK (if using 3.x) or version 4.1.1 or later (if using the 4.x). On React Native, the corresponding minimum versions are 10.12.0 and 11.4.0. Aside from updating your SDK, no action is required to enable SNA. * Added support for biometric authentication for Citibank for integrations using the iOS SDK version 5.1.0 or later. * Released account holder category (beta), indicating whether an account returned in the account object is a business or personal account. To request access to this feature, contact your account manager. For Plaid Link SDKs: * Released Android SDK 4.6.0, containing bug fixes and compatibility improvements. For details, see the [Android SDK changelog](https://github.com/plaid/plaid-link-android/releases) . For Auth: * Released [AUTH: DEFAULT\_UPDATE](https://plaid.com/docs/api/products/auth/index.html.md#default_update) webhook to GA. This webhook fires if Plaid detects that a bank's Auth information has changed. (While rare, this can occur due to changes such as an acquisition.) To avoid ACH returns, after receiving this webhook, you should call [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) to update your information on file for the user. For Identity: * In [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , `legal_name.is_business_name_detected` is no longer deprecated and can now be used for detecting business names. For Transfer: * Added [return\_rates](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfer-metrics-get-response-return-rates) field to [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) , allowing you to get return rate information via the API. ##### June 2024  * Launched [Plaid Layer](https://plaid.com/docs/layer/index.html.md) to early availability. Layer provides a fast, high-converting onboarding experience powered by Plaid Link. * Launched [Plaid Check](https://plaid.com/docs/check/index.html.md) , a subsidiary of Plaid Inc. that is a Consumer Reporting Agency. Through Plaid Check's Consumer Report API, you can retrieve ready-made credit risk insights from consumer-permissioned cash flow data. * Decommissioned the Development Environment. Development has been replaced for testing purposes by Limited Production. For Plaid Link SDKs: * Released iOS SDK 5.6.0, containing support for Plaid Layer, as well as bug fixes and improvements to the returning user experience. * Released iOS SDK 4.7.9, containing bug fixes and improvements to the returning user experience. * Released Android SDK 4.5.0, containing support for Plaid Layer, as well as bug fixes. * Released React Native 11.11.0, containing support for Plaid Layer, as well as bug fixes and improved prefill support. For Beacon: * Added `access_tokens` field to [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) and [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) requests. * Added `item_ids` to `/beacon/user/*` responses. * Added Bank Account Insights to Beacon. Account Risk (beta) is being folded into Beacon For Balance: * Launched Balance Plus (beta). Balance Plus enhances Plaid's Balance product with additional insights and lower latency and is designed to require minimal integration work for existing Balance customers. For Income: * Launched [Plaid Check](https://plaid.com/docs/check/index.html.md) , a subsidiary of Plaid Inc. that is a Consumer Reporting Agency. Through Plaid Check's Consumer Report API, you can retrieve ready-made credit risk insights from consumer-permissioned cash flow data. * Added [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) to support the deletion of user tokens. For Liabilities: * Added `income-sensitive repayment` as a student loan repayment type. For Transactions: * As originally announced in the November 2023 changelog, the default number of days of transactions history requested for new transactions-enabled Items is now 90 days for all customers. To change this behavior, use the `days_requested` parameter in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) or (if initializing transactions post-Link) [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) or [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . * Improved behavior of Transactions-enabled Items being fixed via update mode. Now, if an Item was in an error state for over 24 errors before entering update mode, Plaid will immediately extract fresh transactions after update mode has completed, rather than waiting for the next scheduled update time. For Transfer: * Added support for RTP to Transfer UI. * Added improved support for Transfer limit increase requests via the Transfer Dashboard. For Virtual Accounts: * Added support for `RECALL` as a transaction type where the sending bank has requested the return of funds due to a fraud claim, technical error, or other issue associated with the payment. ##### May 2024  * Released [Limited Production](https://plaid.com/docs/quickstart/glossary/index.html.md#limited-production) , which will replace Development as a platform for testing for free with live data. The Development environment will be decommissioned on June 20, 2024, and all Development Items will be deleted. * Released [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) to GA. To help ensure compliance with 1033 rulemaking, DTM will be automatically enabled for US and CA Link sessions later this year. * Added new pre-seeded Sandbox test accounts for testing different credit profiles. These accounts are especially useful for testing Income, but are available to all customers. For details, see [Credit and Income testing credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#credit-and-income-testing-credentials) . * Updated the response object for [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) . To accommodate future multi-Item Link session support for additional products, the `on_success` object in the response has been deprecated; it is recommended to use the new `results` object instead. Old: `link_sessions[0].on_success.public_token`. New: `link_sessions[0].results.item_add_results[0].public_token`. The `on_exit` field has also been deprecated; it is recommended to use the new `exit` field. * Updated the `SESSION_FINISHED` webhook. To accommodate future multi-Item Link session support for additional products, deprecated the `public_token` field in lieu of a new `public_tokens` array. For Plaid Link SDKs: * Released iOS SDK 5.5.0 and 4.7.7, containing bug fixes and (for iOS SDK 5.5.0) additional view names to support new functionality. * Released iOS SDK 6.0.0 beta, containing support for Apple Card and FinanceKit. * Released Android SDK 4.4.1, containing bug fixes and UI improvements. * Released React Native SDK 11.10.1, with improved support for "pre-loading" Link for a lower-latency user experience. * Released React Native SDK 12.0.0 beta, containing support for Apple Card and FinanceKit. For Income: * Added new values to `canonical_description` in [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) : `RETIREMENT`, `GIG_ECONOMY`, and `STOCK_COMPENSATION`. For Signal: * Added support for some Items added via Same Day Micro-deposits or Instant Micro-deposits. For Transfer: * Added [/transfer/authorization/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcancel) endpoint. ##### April 2024  * Updated [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) response to include `user_token`. * Rebranded Remember Me as returning user experience. For Plaid Link SDKs: * Released Android SDK 4.3.1, iOS SDK 4.5.2, and React Native SDK 11.8.2, containing bug fixes and UI enhancements. For Auth: * Released Database Match, which enables instant manual account verification using Plaid's database of known account numbers. When provided as an alternative to Same Day Micro-deposits, Database Match can increase conversion, as the user may be able to verify instantly, without having to return to Plaid to verify their micro-deposit codes. * Released [Database Insights (beta)](https://plaid.com/docs/auth/coverage/database/index.html.md) . Database Insights can be used as a manual alternative to credential-based Auth flows in low-risk use cases. Database Insights verifies account and routing numbers by checking the information provided against Plaid's known account numbers. If no known account number is found, Database Insights checks the information given against usages associated with the given routing number. For more information and to request access to the beta, see the [Database Insights (beta) documentation](https://plaid.com/docs/auth/coverage/database/index.html.md) . * Added support for the `SMS_MICRODEPOSITS_VERIFICATION` webhook to [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) to support testing the [Text Message Verification flow](https://plaid.com/docs/auth/coverage/same-day/index.html.md#using-text-message-verification) . For Income: * Added the ability to customize test data in the Sandbox environment for use with Document Income, by uploading a special JSON configuration object during the document upload step. For details, see [Testing Document Income](https://plaid.com/docs/income/document-income/index.html.md#testing-document-income) . For Payment Initiation: * Added `supports_payment_consents` field to an institution's Payment Initiation metadata object. * Added counterparty date of birth and address as optional request fields for [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) . Providing these fields increases the likelihood that the recipient's bank will process the transaction successfully. For Statements: * Released [Statements](https://plaid.com/docs/statements/index.html.md) to General Availability. * Added Statements support to [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) . For Transfer: * Updated the possible values for `network` in recurring transfer contexts to reflect the fact that recurring transfers now support RTP. * Added `funds_available` transfer status and transfer event type. * Deprecated the `/transfer/balance/get` endpoint in favor of the Plaid Ledger. ##### March 2024  For Plaid Link SDKs: * Multiple improvements to the Remember Me experience. * Added the ability to "pre-load" Link for a lower-latency user experience. For Auth: * Enabled [Text Message Verification](https://plaid.com/docs/auth/coverage/same-day/index.html.md#using-text-message-verification) flow for Same-Day Micro-deposits by default. This new, non-breaking change can increase conversion of micro-deposit verification by up to 15%. This flow is now enabled for all Same Day Micro-deposit flows by default; to opt-out, use the `auth.sms_microdeposits_verification_enabled: false` setting when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . For Transactions: * Multiple improvements to the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint addressing common pain points: * [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) now returns the `accounts` array, eliminating the need for a separate call to [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) . * [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) now returns a `transactions_update_status`, reflecting the status of the transaction pulls, which was previously only available via webhook. * The list of `removed` transactions now includes the `account_id`s they were associated with, to make reconciliation and management easier. * Granted all customers self-serve access to the `original_description` field. To access original transaction descriptions, set `options.include_original_description` to `true` when calling [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) or [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . It is no longer necessary to request access from your account manager. * Made `account_id` optional in the [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) endpoint. For Transfer: * Added `has_more` field to [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) and [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) to indicate there are more events to be pulled. * Updated the possible values for `network` in recurring transfer contexts to reflect the fact that recurring transfers are only supported via ACH. For Processor Partners: * Added `institution_id` to [/processor/account/get](https://plaid.com/docs/api/processor-partners/index.html.md#processoraccountget) endpoint. ##### February 2024  For Auth: * Released the [Text Message Verification](https://plaid.com/docs/auth/coverage/same-day/index.html.md#using-text-message-verification) flow for Same-Day Micro-deposits. This new, non-breaking change can increase conversion of micro-deposit verification by up to 15%. Currently, Text Message Verification is opt-in, and will transition to opt-out in March. For Identity Verification: * Added a large number of additional `linked_services` enum values. For Investments: * Added `vested_quantity` and `vested_value` fields to the `holdings` object. For Liabilities: * Added the `pending idr` status for student loans to reflect loans with a pending application for income-driven repayments. For Transfer: * Added fields including `wire_details` and `wire_routing_number`, and `wire` as a supported `network`, to support wire transfers. If you are interested in using wire transfers with Transfer, contact your account manager or (if you are not yet a customer) sales. * Increased maximum length of `description` field on [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) from 8 to 15. For Signal: * Added `warnings` array to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) response even if no warnings are present in order to match documented API behavior. ##### January 2024  * Expanded the Returning User Link flow to more customers. For more details on the returning user experience, including the associated Link events, see [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) . * Added `events` field to [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to capture Link events. * Made the `persistent_account_id` field available in GA to all customers. The `persistent_account_id` field is a special field, available only for Chase Items. Because Chase accounts have a different account number each time they are linked, this field may be used instead of the account number to uniquely identify a Chase account across multiple Items for payments use cases, helping to reduce duplicate Items or attempted fraud. * Released the [USER\_ACCOUNT\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_account_revoked) webhook in GA to all customers, to complement the existing [USER\_PERMISSION\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) webhook, but capturing account-level revocation rather than Item-level revocation. The `USER_ACCOUNT_REVOKED` webhook is sent only for Chase Items and is primarily intended for payments use cases. The webhook indicates that the TAN associated with the revoked account is no longer valid and cannot be used to create new transfers. For Auth: * Added support for the Stripe Payment Intents API. For more details, see [Add Stripe to your App](https://plaid.com/docs/auth/partnerships/stripe/index.html.md) . For Assets: * Added `vested_quantity` and `vested_value` fields to the Investments object within the Asset Report. * Added `margin_loan_amount` field to the Balance object within the Asset Report. For Enrich: * Added counterparty `phone_number` to the [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) response. For Income: * Added the ability to filter the results of [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) and [/credit/bank\_statements/uploads/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_statementsuploadsget) to only certain Items, via an optional `item_ids` request field. * Added `num_1099s_uploaded` to the `document_income_results` object in [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) response. For Identity Verification: * Added new `no_data` type to `name` and `date_of_birth` fields in `documentary_verification.documents[].analysis.extracted_data` in the response of all of the Identity Verification endpoints. * Made `street` and `city` optional in the address attribute of [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) . For Payment Initiation: * Added optional `scope` and `reference` fields to [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) . For Transactions: * Added a new Sandbox test user, `user_transactions_dynamic`. When logging into Sandbox with this username, you will see more realistic, dynamic Sandbox transactions data, including a wider variety of transaction types, and transactions moving between pending and posted state. For Virtual Accounts: * Added `available` balance to balance object in [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) and [/wallet/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletlist) . For Partners: * Added [/processor/liabilities/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorliabilitiesget) endpoint. * Added optional `registration_number` to [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) request. ##### December 2023  * Announced the upcoming removal of the Development environment. To simplify the development process, Plaid will be replacing the Development environment with the ability to test with real data for free directly in Production. On June 20, 2024, the Plaid Development environment will be decommissioned, and all Development Items will be removed. You may continue to test on the Development environment until this time. * Capital One now provides real-time balance data for depository accounts, including checking and savings accounts. It is no longer necessary to include `min_last_updated_datetime` when making [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) calls for these accounts. For Investments: * Added `market_identifier_code` to the security object. * Added `option_contract` to the security object, adding additional details `contract_type`, `expiration_date`, `strike_price`, and `underlying_security_ticker` for better insight into derivatives. ##### November 2023  For Identity: * Released [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) and the `/identity/match/` endpoint to General Availability. For Income: * Expanded [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) to support the `INCOME_VERIFICATION_RISK_SIGNALS` webhook, adding a new `webhook_code` parameter to the endpoint. For Transfer Platform Payments (beta): * Added [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) endpoint, as well as a `facilitator_fee` field to [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) , both of which can be used to collect payments from end customers. * Removed support for doc and docx format files in `/transfer/diligence/document/upload`. For Transfer: * Updated default Sandbox behavior of Ledger. Ledgers in Sandbox will now have a $100 default balance. For Transactions: * Added the `days_requested` field to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) and [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) under the `options` object, and to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) under the `transactions` object to support a behavior change in the Transactions product. For all new customers who created accounts after December 3, 2023 the maximum number of days of historical data requested from transactions endpoints will default to 90 days if the `days_requested` field is not specified. This change will also be applied to existing customers on June 24, 2024. To change the amount of historical data requested, use the `days_requested` field when Transactions is first added to your Item. For Partners: * Added [/processor/signal/prepare](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalprepare) * Added [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) * Make `products` field in `/partner/customers/create` optional. If empty or `null`, this field will default to the products enabled for the partner. ##### October 2023  * Chase has extended the September 30 deadline for migrating away from in-process webviews. The new cutoff date will be in mid-January 2024. All impacted customers should migrate by January 1, 2024 to avoid a negative impact on Link conversion. See the [deprecation notice](https://docsend.com/view/h3qdupjusiwyjvv5) for more details. * Added Belgium as a supported country. For Auth: * Added an `instant_microdeposits_enabled` flag to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to allow customers to disable Instant Micro-deposits. By default, Instant Micro-deposits will be enabled for all sessions. For Income: * Released Document Fraud to General Availability. * Added [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) , allowing users of Document Fraud to update the parsing configuration used for document income. * Deprecated the /credit/payroll\_income/precheck endpoint. For Investments: * Added the `investments.allow_manual_entry` parameter in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and the corresponding `is_investments_fallback_item` field to [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) and [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) . Enabling manual entry allows a user to create an investments fallback Item for a non-supported institution by manually entering their holdings in Link. * Extended the deadline beyond which Plaid customers will need a CGS license to obtain `cusip` and `isin` data. The new deadline is March 2024. For Transactions: * Added `counterparties`, `logo_url`, and `website` information about merchants (previously available only via Enrich) to [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) and [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) data. For Transfer: * Added new methods to fund your Plaid Ledger. In addition to the [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) and [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) endpoints, you can now initiate a funds transfer via the Dashboard, set up a recurring schedule or minimum balance by contacting Support, or fund your ledger via ACH or wire transfer from your bank account. * Made Plaid Ledger the default method for funding transfers for all new Transfer customers. Plaid Ledger allows faster funds transfers and is now the easiest way to move money between your bank account and Plaid. Existing customers who want to switch to Plaid Ledger should contact their Plaid account manager. * Added [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) to test refunds in the Sandbox environment. * Added refund-specific event types. These are existing event types with the prefix `refund.`, e.g. `refund.settled`. * For [/transfer/configuration/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transferconfigurationget) , stopped returning `max_single_transfer_amount` and `max_monthly_amount`. To maintain compatibility with older client libraries, these fields will still be present in the API, but will be blank strings. * For [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) , stopped returning `monthly_transfer_volume`. To maintain compatibility with older client libraries, this field will still be present in the API, but will be a blank string. For Virtual Accounts: * Added `RETURN` as possible Virtual Account wallet transaction type. ##### September 2023  * Added the `LOGIN_REPAIRED` webhook. This webhook will fire when an Item's status transitions from `ITEM_LOGIN_REQUIRED` to a healthy state, without the user having used the update mode flow in your app. * Added [Update Mode Product Validations (beta)](https://plaid.com/docs/link/update-mode/index.html.md#resolving-access_not_granted-or-no_auth_accounts-errors-via-product-validations) . Update Mode Product Validations (UMPV) allows you to validate that a user going through update mode at an OAuth institution has selected the appropriate authorizations to enable Auth and/or Identity. If they do not select the correct options, they will be prompted to update their selections. * Added [Optional Products](https://plaid.com/docs/link/initializing-products/index.html.md#optional-products) . If a product is specified in the `optional_products` field when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , the product will be added to the Item if possible. However, if the product cannot be added to the Item -- for example, because the Item is not supported by the institution, the user did not grant the correct OAuth permissions, or because of an institution connectivity error for that product -- Item creation will still succeed with the other products specified. * Added `institution_not_supported` as a potential Link session exit metadata status. For Auth: * Added [Instant Micro-Deposits](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-micro-deposits) , allowing end users to verify their accounts in seconds, using micro-deposits sent over RTP or FedNow rails. Instant Micro-Deposits can be used as a faster alternative to Same-Day Micro-Deposits at supported institutions. For Assets: * Deprecated `report_type` field used in [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) , and replaced it with `verification_report_type`. This change was made to avoid confusion with the existing `report_type` field used to by the `PRODUCT_READY` webhook to distinguish between Fast Asset Reports and Full Asset Reports. For Signal: * Launched the Signal Dashboard to help customers monitor return rates and tune Signal risk score thresholds. For Transactions: * Made [Personal Finance Categories](https://plaid.com/docs/transactions/pfc-migration/index.html.md) returned by default for all users. Personal Finance Categories are Plaid's newest and most accurate way of categorizing transactions, using more intuitive categories that correspond better to personal finance management use cases. For Transfer: * Launched Transfer from beta to early availability (EA) status. * Added support for FedNow payments, which can be accessed by specifying `rtp` as the payment network. * Added Plaid Ledger. Your Plaid Ledger allows you to maintain a funds balance with Plaid, which can be used to fund payouts over FedNow and RTP rails. You can use APIs to move money in and our of your Ledger. * Removed Payment Profiles; access tokens are now the only supported mechanisms for connecting accounts on Transfer. * Removed `beacon_id`, as it was used only to support Guarantee. Guarantee is no longer offered and will be replaced by a more sophisticated set of risk management tools within Transfer. For Income: * Updated API docs to reflect `"NOT LISTED"` as a potential value for `marital_status`. For Statements (beta): * Released [Statements](https://plaid.com/docs/statements/index.html.md) in beta. Statements allows you to retrieve an exact PDF copy of a customer's statement at supported institutions. ##### August 2023  For Enrich: * Added `frequency` field to recurring transactions to indicate the recurrence frequency. For Identity Verification: * Added `area_code` match status to the responses of the [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) and [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) endpoints. For Income: * Added a number of new categories for Payroll Income `canonical_description` field: `ALLOWANCE`, `BEREAVEMENT`, `HOLIDAY_PAY`, `JURY_DUTY`, `LEAVE`, `LONG_TERM_DISABILITY_PAY`, `MILITARY_PAY`, `PER_DIEM`, `REFERRAL_BONUS`, `REIMBURSEMENTS`, `RETENTION_BONUS`, `RETROACTIVE_PAY`, `SEVERANCE_PAY`, `SHIFT_DIFFERENTIAL`, `SHORT_TERM_DISABILITY_PAY`, `SICK_PAY`, `SIGNING_BONUS`, and `TIPS_INCOME`. Also made `null` a valid value. * Added `status` field to [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) to show the status of evaluated documents. * Added `payroll_income.parsing_config` to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to expose configuration options for risk signal evaluation. For Liabilities: * Added `saving on a valuable education` (SAVE) as a student loan repayment plan type. For Signal: * Added the ability to change an `initiated` status reported via [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) . Previously, attempting to change the status of a reported decision that was originally reported as `initiated` would result in an `INVALID_FIELD` error; now it is allowed. For Transfer: * Added `failure_reason` to refund objects to indicate why a Transfer refund failed. For Virtual Accounts: * Added `failure_reason` to [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) and [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) endpoints to indicate why a wallet transaction failed. ##### July 2023  * Added [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) endpoint to allow customers using processor partners to update the webhook endpoint associated with a processor token. For Assets: * Made `asset_report_token` optional in [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) request to support future development of Asset Reports based on other types of tokens. For Investments: * Added the `async_update` option for [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) , along with an accompanying `HISTORICAL_UPDATE` webhook. If `async_update` is enabled, the initial call to [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) for an Item will be made as an async call with a webhook, similar to [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) . For Enrich: * Added `confidence_level` to `counterparty` and `personal_finance_category` fields. For Identity Verification: * Added `date_of_birth` and `address` fields to `documentary_verification.documents[].extracted_data` in the response of all Identity Verification endpoints. * Mark all `region` and `postal_code` fields as nullable, to better support countries that do not use these fields. For Transfer: * Added `transfer_id` and `status` filters to [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) request. * Added `status` field to the sweep object. ##### June 2023  * Added the `required_if_supported_products` field to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . When using multiple Plaid products, you can use this field to specify products that must be enabled when the user's institution and account type support them, while still allowing users to add Items if the institution or linked account doesn't support these products. If a product in this field cannot be enabled at a compatible institution (for example, because the user failed to grant the required OAuth permissions, generating an `ACCESS_NOT_GRANTED` error), the Item will not be created, and the user will be prompted to try again in the Link flow. * Changed the behavior of the `oauth` field on the institution object. Previously, `oauth` would be `true` only if _all_ Items at an institution used OAuth connections. Now, `oauth` is true if _any_ Items at an institution use OAuth connections. * Changed the behavior of the `account_selection_enabled` flag in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . To improve conversion, at institutions that provide OAuth account selection flows, this flag will be overridden and treated as though it were always `true`. For other institutions, the flag behavior is unchanged. For Auth: * Added the ability to customize Same-day Microdeposit flows via the new `reroute_to_credentials` option in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Using this field, you can detect whether a user is attempting to use Same-day Microdeposits to add an institution that is supported via a direct Plaid connection, and optionally either require or recommend that they use a direct connection instead. For Enrich: * Added `income_source` enum to `counterparty_type` field. For Identity Verification: * Added the ability to prefill user data when retrying a verification by providing a `user` object to [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) . * Added `client_user_id` field to [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) . It is recommended to use this field instead of `user.client_user_id`, although both fields are supported. For Income: * Added `num_bank_statements_uploaded` to `document_income_results` object in [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) . For Signal: * Removed the maximum length constraint for `client_user_id` when calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) or [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) . For Transfer: * Added the ability to specify a `test_clock_id` when calling [/sandbox/transfer/sweep/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersweepsimulate) or [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) . If provided, the simulated action will take place at the `virtual_time` of the given test clock. * Made the `virtual_time` field optional when calling [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) . If a time is not provided, the current time will be used. * Updated the `sweep_id` format to be either a UUID or an 8-character hexadecimal string. * Made `next_origination_date` nullable in the recurring transfer object. For Virtual Accounts: * Added address and date of birth to [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) . * Added payment scheme (`scheme`) to [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) and [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) . ##### May 2023  For Assets: * Added support for `ASSETS: PRODUCT_READY` and `ASSETS: ERROR` webhooks to [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) For Identity: * Added `is_business_name_detected` to the [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) endpoint For Identity Verification: * Added the `selfie_check` field to the Income Verification object, to report the status of a selfie check. For Document Income: * Added the `INCOME_VERIFICATION_RISK_SIGNALS` webhook to indicate when [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) is ready to be called. For Transfers: * Increased the maximum length of the `description` field in [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) to 15 characters. * Added the `/transfer/balance/get` endpoint. * To support prefunded credit processing, added the `credit_funds_source` field to distinguish between credits based on sweeps, RTP credit balances, and ACH credit balances, and made the `funding_account_id` field nullable. For Processor partners: * Added [/processor/token/permissions/set](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsset) and [/processor/token/permissions/get](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsget) endpoints. * Added [/processor/identity/match](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentitymatch) endpoint to allow Processor partners to support the new beta Identity Match feature. For Signal: * Added a `warnings` object to the [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) response. ##### April 2023  For Income: * Added `STARTED` and `INTERNAL_ERROR` statuses to [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) . For Document Income: * Released the [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) endpoint. This endpoint can be used as part of the Document Income flow to assess a user-uploaded document for signs of potential fraud or tampering. For Identity Verification: * Documented several fields in the `user` object of [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) as being officially supported methods of pre-filling user data in Link for the Identity Verification flow, as an alternative to [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) . (While this worked in the past, it was not previously an officially supported or documented flow.) As part of this change, un-deprecated the `user.date_of_birth` field. For Enrich: * Added `recurrence` and `is_recurring` fields to [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) . ##### March 2023  * To maximize conversion, updated Link to use a pop-up window for OAuth authentication rather than redirects on non-webview mobile web flows. * Clarified that `continue(from:)` is no longer required for iOS OAuth integrations using Plaid's iOS and React Native iOS SDKs. * Updated error codes for most `RATE_LIMIT` errors to be specific to the endpoint for which they apply. For Auth: * Changed the Link UI for Instant Match and Automated Micro-deposits flows to increase conversion by reducing the number of screens in the flow and removing unnecessary input fields. No developer action is required as a result of this change. For Transactions: * Added `ANNUALLY` as a possible frequency for recurring transactions in [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) . For Identity: * Added [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) (beta) to simplify the process of using Identity for account ownership verification. [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) allows you to send user information such as name, address, email, and phone number, and returns a match score indicating how closely that data matches information on file with the financial institution, so that you no longer have to implement similarity matching logic on your own. [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) is currently in closed beta; to request access, contact your account manager or [contact sales](https://www.plaid.com/contact) . For Identity Verification: * Added [risk\_check object](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) to [Identity Verification API responses](https://plaid.com/docs/api/products/identity-verification/index.html.md) to provide more detail about the factors that influenced the risk check result. For Assets: * Released Fast Assets functionality to General Availability (GA). With Fast Assets, you can create a Fast Asset Report with partial information (current balance and identity data) in about half the time as a Full Asset Report, then request the Full Asset Report later. Fast Assets is available free of charge to all Assets customers. For more information, see the [Assets API reference](https://plaid.com/docs/api/products/assets/index.html.md#asset_report-create-request-options-add-ons) . * Added the optional `days_to_include` field to [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) requests. This field allows you to optionally reduce the number of days displayed in an Asset Report, to improve usability for human reviewers. * Added Freddie Mac as an audit copy token partner with `auditor_id: freddie_mac`. * Added `credit_category` (beta) to transactions data returned by Asset Reports with Insights, describing the category of the transaction. Access to this field is in closed beta; to request access, contact your account manager. For Income: * Added support for `bank_employment_results` data to [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) . Employment functionality is currently in closed beta; for more details, contact your account manager. For Signal: * Added `warnings` field to [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) response. For Virtual Accounts: * Added `transaction_id` to the Payment Initiation `PAYMENT_STATUS_UPDATE` webhook. This field will be present only when a payment was initiated using Virtual Accounts. * Added `payment_id` and `wallet_id` to the `WALLET_TRANSACTION_STATUS_UPDATE` webhook. ##### February 2023  * Added the `persistent_account_id` field (beta) to the `account` object. The `persistent_account_id` field identifies an account across multiple instances of the same Item, for use with Chase Items only, to simplify the management of Chase [duplicate Item behavior](https://plaid.com/docs/link/oauth/index.html.md#chase) . Access to this field is currently in closed beta; for more details, contact your account manager. For Assets: * Beginning March 31, 2023, Assets will be updated to return `investment`, instead of `brokerage`, as the account type for investment accounts. `brokerage` may still be returned as an account sub-type under the `investment` account type. For Income: * Added `employment` value to the `products` array for [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Employment functionality is currently in closed beta; for more details, contact your account manager. For Identity Verification: * Added `redacted_at` field in Identity Verification response and Documentary Verification Document component. For Transfer: * Added the ability to specify a payment `network` (either `ach` or `same-day-ach`) when calling [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) . For reseller partners: * Added `income_verification` and `employment` as supported products for [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) . Employment functionality is currently in closed beta. * Added the ability to specify `redirect_uris` to [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) . For Virtual Accounts: * Increased the minimum length of the `reference` field for [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) to 6 characters. * To improve usability, added `wallet_id` field to [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) and [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) responses and to the [WALLET\_TRANSACTION\_STATUS\_UPDATE](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallet_transaction_status_update) webhook. For Payment Initiation: * Increased the minimum length of the `reference` field for [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) to 6 characters. * To improve usability, added `transaction_id` field to the [PAYMENT\_STATUS\_UPDATE](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_status_update) webhook. This field will be populated when the payment status is `PAYMENT_STATUS_SETTLED`. * Removed the deprecated `options.wallet_id` field from [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) and [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) . For Signal: * Added `signal` to the products array. For most current Signal customers, Signal is automatically enabled for all of their Items; over time, Signal will be moving to a model similar to Plaid's other products, in which customers instead initialize an Item with signal by adding `signal` to the products array when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . ##### January 2023  * Released Plaid [React Native SDK 9.0.0](https://github.com/plaid/react-native-plaid-link-sdk) and Plaid [iOS SDK 4.1.0](https://github.com/plaid/plaid-link-ios) . All iOS integrations must upgrade to these SDKs by June 30, 2023 in order to maintain support for Chase OAuth flows on iOS. Any integrations using webviews will also be required to update their webview handlers by June 30, 2023. For more details on required webview updates, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md#extending-webview-instances-to-support-certain-institutions) . * Released improvements to the [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) : removing the requirement to provide a verified time for phone numbers and email addresses, making RUX flows available for more products, and adding Institution Boosting, which automatically surfaces institutions a user has previously linked to Plaid in the Link flow. Enabling the returning user experience can increase conversion by 8% or more. For more details, see [Returning user experience documentation](https://plaid.com/docs/link/returning-user/index.html.md) . For Auth: * Updated [Same-Day Micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) to make a single one-cent micro-deposit, which will not be reversed, rather than multiple micro-deposits. This change will reduce costs and decrease the incentive for micro-deposit fraud. No changes are required on the part of developers to support this change. This change will automatically be rolled out to customers over the next several months. For Transfer: * Added `expected_settlement_date` field to the Transfer object. * Added `funding_account_id` field to clarify which account is used to fund a transfer. This field replaces the older `origination_account_id`. For Virtual Accounts: * Added `status` field to Wallet schema. For Partners: * Added [PARTNER\_END\_CUSTOMER\_OAUTH\_STATUS\_UPDATED](https://plaid.com/docs/api/partner/index.html.md#partner_end_customer_oauth_status_updated) webhook. ##### December 2022  For Auth: * Announced upcoming [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) automatic enrollment to existing customers who have not yet been enabled for Instant Match by default. Instant Match is a higher-converting experience for Link that expands Auth coverage to more end users. All customers will be enabled for Instant Match by default unless they opt-out by January 19, 2023, which they can do by contacting their account manager. For Assets: * Released relay tokens to beta, along with associated endpoints [/credit/relay/create](https://plaid.com/docs/api/products/assets/index.html.md#creditrelaycreate) , [/credit/relay/get](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayget) , [/credit/relay/refresh](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayrefresh) , and [/credit/relay/remove](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayremove) . Relay tokens support sharing of Asset Reports with customers' authorized service providers, such as underwriters. For Income: * For [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) , deprecated `amount`, `iso_currency_code`, and `unofficial_currency_code` at top levels in response in favor of new `total_amounts` field. This change enables more accurate reporting of income for users with income in multiple different currencies. * Added new possible values to `rate_of_pay` field returned by [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) : `WEEKLY`, `BI_WEEKLY`, `MONTHLY`, `SEMI_MONTHLY`, `DAILY`, and `COMMISSION`. * Added new `pay_basis` field to the response of [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . For Virtual Accounts: * Added `FUNDS_SWEEP` as a possible transaction type. For Transfer: * Added [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) endpoint to provide information about which Items support Real Time Payments (RTP) * Added endpoints /transfer/originator/get, /transfer/originator/list, /transfer/originator/create, and /transfer/questionnaire/create to support marketplaces and reseller partners in creating and managing transfer originators. * Added the ability to create and manage [recurring transfers](https://plaid.com/docs/transfer/recurring-transfers/index.html.md) . API changes include the new endpoints `/transfer_recurring/create`, [/transfer/recurring/cancel](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcancel) , [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) , and [/transfer/recurring/list](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringlist) , as well as the new webhooks `RECURRING_NEW_TRANSFER`, `RECURRING_TRANSFER_SKIPPED`, and `RECURRING_CANCELLED`, and the test endpoints [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) , [/sandbox/transfer/test\_clock/advance](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockadvance) , [/sandbox/transfer/test\_clock/get](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockget) , and [/sandbox/transfer/test\_clock/list](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clocklist) . For Enrich: * Released Enrich to early availability. Enrich access is now available by default in Sandbox. For details on requesting access to use Enrich with real data, see the [Enrich documentation](https://plaid.com/docs/enrich/index.html.md) . * Added support for legacy categories, using categories from [/categories/get](https://plaid.com/docs/api/products/transactions/index.html.md#categoriesget) , in addition to the newer `personal_finance_category` schema. * Renamed counterparty type `delivery_marketplace` to `marketplace` and added counterparty type `payment_terminal`. For the Reseller Partner API: * Added [/partner/customer/oauth\_institutions/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomeroauth_institutionsget) endpoint to provide OAuth-institution registration information to Reseller Partners. ##### November 2022  * Released [Signal](https://plaid.com/docs/signal/index.html.md) to general availability. Signal uses machine learning techniques to evaluate a proposed ACH transaction and determine the likelihood that the transaction will be reversed. It also provides fields and insights that you can incorporate into your own data models. By using the Signal API, you can release funds earlier to optimize your user experience while managing the risk of ACH returns. For Auth: * Enabled [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) by default for most existing customers. For Investments: * Notified customers that customers must hold a CGS (CUSIP Global Services) license to obtain CUSIP and ISIN data. Beginning in mid-September 2023, customers who do not have a record of this license with Plaid will receive `null` data in these fields. To maintain access to these fields, contact your Plaid account manager or [investments-vendors@plaid.com](https://plaid.commailto:investments-vendors@plaid.com) . For Payment Initiation: * Added the ability to initiate partial refunds by specifying an `amount` when calling [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) . As part of this change, added `amount_refunded` field to [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) and [/payment\_initiation/payment/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentlist) . * Added support for local payment schemes for all supported currencies (previously, only EUR and GBP local payment schemes been supported), and added the enum values `LOCAL_DEFAULT` and `LOCAL_INSTANT` to represent them. In the UK, the `FASTER_PAYMENTS` enum value has been replaced by `LOCAL_DEFAULT`. * Removed support for currencies CHF and CZK. For Virtual Accounts: * For improved consistency, renamed `/wallet/transactions/list` to [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) . * For clarity, renamed `start_date` to `start_time` in the [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) response to reflect that the field is a date-time. For Transfer: * Made `account_id` nullable in the responses for [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) and [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) . * Added `deleted_at` field to /payment\_profile/get response. * Added `refunds` field to the transfer object. * Added `refund_id` to the transfer event object. For Reseller Partners: * Added the [/partner/customer/remove](https://plaid.com/docs/api/partner/index.html.md#partnercustomerremove) endpoint to disable customers who have not yet been enabled in Production. ##### October 2022  * Added support for additional Link display languages: Danish, German, Estonian, Italian, Latvian, Lithuanian, Norwegian, Polish, Romanian, and Swedish. * Added support for additional countries: Denmark, Estonia, Latvia, Lithuania, Poland, Norway, and Sweden. * Added support for `USER_INPUT_TIMEOUT` as a value for `force_error` in the [Sandbox custom user](https://plaid.com/docs/sandbox/user-custom/index.html.md) schema. For Auth: * Enabled [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) by default for all new customers. For Investments: * Added `non-custodial wallet` to account subtypes. * Added `trade` investment transaction subtype as a subtype of `transfer` investment transaction type For Income: * To improve reliability and developer ease of use, modified the multi-Item Link flow for Bank Income to use the new [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) endpoint rather than relying on Link events. * Added Bank Income status `USER_REPORTED_NO_INCOME`. * Added Income support to [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) . * Deprecated `VERIFICATION_STATUS_PENDING_APPROVAL`. * Established a 128 character limit for the `client_user_id` field in the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) request. * Added `institution_name` and `institution_id` fields to [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) response. For Virtual Accounts: * Added `options.start_time` and `options.end_time` to [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) request. * Added `last_status_update` and `payment_id` field to wallet transactions. For Payment Initiation: * Added `transaction_id` field to the payment object. For Transfer (beta): * Added support for RTP networks * Added decision rationale code `PAYMENT_PROFILE_LOGIN_REQUIRED` and the ability to update a Payment Profile via update mode. Also added /sandbox/payment\_profile/reset\_login to test this new update mode flow in Sandbox. * To improve consistency, renamed `LOGIN_REQUIRED` decision rationale to `ITEM_LOGIN_REQUIRED`. * Deprecated `origination_account_id` from [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) endpoint. * Added new `originator_client_id` field to support Third-Party Senders (TPS). For Wallet Onboard (beta): * Released Wallet Onboard to beta. For Partner Resellers: * Added [Partner reseller endpoints](https://plaid.com/docs/api/partner/index.html.md) to improve the experience of onboarding new customers for delegated diligence partners. ##### September 2022  * Added the ability to simulate the `USER_INPUT_TIMEOUT` error in [Sandbox](https://plaid.com/docs/sandbox/test-credentials/index.html.md#error-testing-credentials) . * Added the ability to specify account mask when using [custom Sandbox users](https://plaid.com/docs/sandbox/user-custom/index.html.md) . For Investments: * Added support for crypto wallet investment account subtype `non-custodial wallet` and crypto `trade` investment transaction type. * Made `institution_price_as_of` nullable. For Transfer (beta): * Added support for client-side beacons. A beacon is now required when using Guarantee with web checkout flows. * Removed the `idempotency_key` from the [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) response. * Added `settled` and `swept_settled` transfer events and event statuses. * Added `standard_return_window` and `unauthorized_return_window` fields to the Transfer object. For Payment Initiation: * Added `AUTHORISING` wallet status. * Added `recipient_id` to the [/wallet/create](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletcreate) , [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) , and [/wallet/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletlist) responses. For Assets: * Added `days_to_include` and `options` to [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) request. ##### August 2022  * Released [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) and [Monitor](https://plaid.com/docs/monitor/index.html.md) to General Availability (GA). * Added `issuing_region` as a field in the extracted data for Identity Verification documents * Extended support for Android Link SDK versions prior to 3.5.0, iOS Link SDK versions prior to 2.2.2, and Link React Native SDK versions prior to 7.1.1. Previously, these SDK versions had been scheduled to be sunset on November 1, 2022. The sunset has been canceled and Plaid will now continue to support these versions past November 2022. We still recommend you use the latest SDK versions. For Payment Initiation: * Added support for [virtual accounts](https://plaid.com/docs/payment-initiation/virtual-accounts/index.html.md) . * Added support for additional currencies PLN, SEK, DKK, NOK, CHF, and CZK. * Added `PAYMENT_STATUS_SETTLED` payment status. For Income: * Removed verification fields from [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) and /income/verification/paystubs/get * Removed `pull_id` field from [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) * Added payroll institution to /credit/income/precheck ##### July 2022  For [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) `user` object: * Deprecated the unused fields `ssn`, `date_of_birth`, and `legal_name`. * Added the `name`, `address`, and `id_number` parameters to support Identity Verification. For Payment Initiation: * Added `bin` as a field under `institution_metadata` for [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . For Income: * Add `stated_income_sources` as a field under `income_verification` for [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . * Add 1099 data to [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) response. * Deprecate `paystubs.verification` in [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) response. For Transfer: * Add `payment_profile_id` to [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) , [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) , and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and make `account_number` and `access_token` optional for [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) and [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) . These changes will support forthcoming Transfer functionality. * Add `user_present` a required field for [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) when using Guarantee (beta) * Deprecated the no-longer-used `swept` and `reverse_swept` statuses. ##### June 2022  For Auth: * Launched [Auth Type Select](https://plaid.com/docs/auth/coverage/flow-options/index.html.md#adding-manual-verification-entry-points-with-auth-type-select) (formerly known in beta as Flexible Auth or Flex Auth) to all customers. Auth Type Select allows you to optionally route end users directly to micro-deposit-based verification, even if they are eligible for Instant Match or Instant Auth. For Transfer: * Made Plaid Guarantee available in beta. Guarantee allows you to guarantee the settlement of an ACH transaction, protecting you against fraud and clawbacks. * Added `TRANSFER_LIMIT_REACHED` to Transfer authorization decision rationale codes. For Income: * Added the `accounts` object with `rate_of_pay` data to the response for [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . For Payment Initiation (UK and Europe only): * Launched payment consents, which can be used to initiate payments on behalf of the user. ##### May 2022  * Added [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) and [Monitor](https://plaid.com/docs/monitor/index.html.md) products in Early Access. Identity Verification checks the identity of users against identity databases and user-submitted ID documents, while Monitor checks user identities against government watchlists. For Transactions: * Added [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , which improves ease of use for handling transactions updates. While [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) continues to be supported and there are no plans to discontinue it, all new and existing integrations are encouraged to use [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) instead of the older [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) endpoint. For Income: * Added `employee_type` and `last_paystub_date` to [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) response. * Removed `uploaded`, `created` and `APPROVAL_STATUS_APPROVED` enum strings, as these are no longer used. ##### April 2022  * Added the ability to default Link to highlighting a specific institution when launching Link, via the [institution\_data](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-institution-data) request field. * Launched [Income](https://plaid.com/docs/income/index.html.md) to general availability. Income allows you to verify the income of end users for purposes of loan underwriting. Various updates were also made to Income interfaces prior to launch; Income beta customers have been contacted by their account managers with details on the differences between the beta API and the released API. For Transactions: * Added [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) , which provides information about recurring transaction streams that can be used to help your users better manage cash flow, reduce spending, and stay on track with bill payments. This endpoint is not included by default as part of Transactions; to request access to this endpoint and learn more about pricing, contact your Plaid account manager. For Auth: * Added Highnote as a processor partner. For a full list of all Auth processor partners, see [Auth Payment Partners](https://plaid.com/docs/auth/partnerships/index.html.md) . ##### March 2022  * Introduced the Institution Select shortcut, which enables you to highlight a matching institution on the Institution Select pane. * Added `institution_data` request field to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint, which accepts `routing_number`. * Added `match_reason` to metadata field for `MATCHED_SELECT_INSTITUTION`, which indicates whether `routing_number` or `returning_user` resulted in a matched institution. * Added support for `AUTH_UPDATE` and `DEFAULT_UPDATE` webhooks to [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) . Also added `webhook_type` parameter to this endpoint to support different `DEFAULT_UPDATE` webhooks for Transactions, Liabilities, and Investments. For Income: * New set of API endpoints added and numerous updates made for General Availability release. Existing beta endpoints are still supported but marked as deprecated. For more details, see the [Income docs](https://plaid.com/docs/income/index.html.md) and [Income API reference](https://plaid.com/docs/api/products/income/index.html.md) . For Auth: * Added Apex Clearing, Checkout.com, Marqeta, and Solid as processor partners. For Payment Initiation: * Added support for the `IT` country code. * Added support for searching by `consent_id` to [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) . For Bank Transfer (beta): * Added `wire_routing_number` parameter to [/bank\_transfer/migrate\_account](https://plaid.com/docs/bank-transfers/reference/index.html.md#bank_transfermigrate_account) . For Transfer (beta): * Removed `permitted` decision for [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) . * Added [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) endpoint. ##### February 2022  * For Transactions, released new personal finance categories to provide more intuitive and usable transaction categorization. Personal finance categories can now be accessed by calling [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) with the `include_personal_finance_category` option enabled. * For Income, removed several unused fields and endpoints, including removing `income_verification_id` from [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) and removing the /income/verification/summary/get and /income/verification/paystub/get endpoints. For Transfer (beta): * Deprecated the `idempotency_key` parameter, as idempotency is now tracked via other identifiers. * Made `repayment_id` a required parameter for /transfer/repayment/return/list. * Made guaranteed fields required in Transfer endpoints. ##### January 2022  * Added the ability to test the `NEW_ACCOUNTS_AVAILABLE` webhook via [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) . * Updated [/item/webhook/update](https://plaid.com/docs/api/items/index.html.md#itemwebhookupdate) to accept empty or `null` webhook URLs. * Updated institutions endpoints to accept null values as input for optional input fields. For Transfer (beta): * Added publicly documented sweep endpoints to provide visibility into the status of Transfer sweeps. * Added `iso_currency_code` throughout the API to future-proof for multi-currency support (currently only USD is supported). * Made `repayment_id` required in /transfer/repayment/return/list endpoint For Bank Transfer (beta): * Removed `receiver_pending` and `receiver_posted` from bank transfer event types, and removed receiver details from events. For Payment Initiation: * Added payment scheme support for EU payments. * Removed `scheme_automatic_downgrade` from [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) . * Updated webhooks to use new statuses. For Income: * Added `DOCUMENT_TYPE_NONE` value for document type. * Made employer address fields no longer required in /income/verification/precheck. ##### December 2021  * For Transfer, updated the schema definitions for [/transfer/intent/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentget) and [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) . * For Income, deprecated the status `VERIFICATION_STATUS_DOCUMENT_REJECTED`. * For Payment Initiation, added several new statuses, including `PAYMENT_STATUS_REJECTED`. ##### November 2021  * For Payment Initiation, added the new status `PAYMENT_STATUS_EXECUTED` and renamed `emi_account_id` to `wallet_id`. * For [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) , added the fields `merchant_name` and `check_number` to the Transactions schema, to match the Transactions schema already being used by the Transactions API. * For Income, added the new status `VERIFICATION_STATUS_PENDING_APPROVAL`. ##### October 2021  Multiple changes to the Income API: * Added the ability to verify submitted paystubs against a user's transaction history by adding the `income_verification.access_tokens` parameter to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and updating /income/verification/paystubs/get to return the income verification status for each paystub. * Added a `precheck_id` field to /income/verification/create and an `income_verification.precheck_id` field to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to fully support use of the /income/verification/precheck endpoint to check whether a given user is supportable by the Income product. * Extensive changes to the paystub schema returned by /income/verification/paystubs/get, including adding new fields and deprecating old ones. For details, contact your Plaid account manager. * Officially deprecated the `income_verification_id` in favor of the Link token-based income verification flow. * Added an `item_id` field to the [income\_verification webhook](https://plaid.com/docs/api/products/income/index.html.md#income_verification) and corresponding [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) endpoint. * Added `employer.url` and `employer.address` fields to the /income/verification/precheck endpoint. * Added a `doc_id` field to /income/verification/taxforms/get. Other changes: * For institutions endpoints, marked the `status` enum as deprecated in favor of the more detailed `breakdown` object. * Added `DE` as a supported country to support Payment Initiation use cases. ##### September 2021  * Released Account Select v2, including the new [NEW\_ACCOUNTS\_AVAILABLE](https://plaid.com/docs/api/items/index.html.md#new_accounts_available) webhook, for improved end-user sharing controls. All implementations must migrate to Account Select v2 by March 2022. * Added the ability to check which types of [Auth coverage](https://plaid.com/docs/auth/coverage/index.html.md) an institution supports via a new `auth_metadata` object now available from [Institutions endpoints](https://plaid.com/docs/api/institutions/index.html.md) * Added the /income/verification/precheck endpoint to check whether a given user is supportable by the Income product. * Added `initiated_refunds` field to [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) and [/payment\_initiation/payment/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentlist) to show refunds associated with payments. * Added fields `include_personal_finance_category_beta` and `personal_finance_category_beta` to Transactions endpoints as part of a beta for new Transactions categorizations. To request beta access, contact [transactions-feedback@plaid.com](https://plaid.commailto:transactions-feedback@plaid.com) * Removed some fields (`direction`, `custom_tag`, `iso_currency_code`, `receiver_details`) and receiver event types from [Bank Transfer (beta) endpoints](https://plaid.com/docs/api/products/transfer/index.html.md) and made `ach_class` a required field. * Added support for the currency type Bitcoin SV. ##### August 2021  * Released [UX improvements to Link](https://plaid.com/blog/enhancements-to-link-for-an-improved-user-experience/) . * Launched [Plaid OpenAPI schema](https://github.com/plaid/plaid-openapi) and new, [auto-generated client libraries](https://plaid.com/blog/open-api-client-libraries/) for Python, Node, Java, Ruby, and Go to General Availability. * Added the ability to use [custom Sandbox data](https://plaid.com/docs/sandbox/user-custom/index.html.md) with the Investments product. * For [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , added the `check_number` field. * Updated the list of [ACH partners](https://plaid.com/docs/auth/partnerships/index.html.md) , adding Treasury Prime. * For [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) , added `min_last_updated_datetime` option to request. * Multiple schema and endpoint updates for the [Bank Transfers (beta)](https://plaid.com/docs/bank-transfers/index.html.md) and [Income (beta)](https://plaid.com/docs/income/index.html.md) products. beta participants can receive details on updates from their account managers. ##### July 2021  * Added new webhook for Deposit Switch. * Added optional `country_code` and `options` parameters to deposit switch creation endpoints, as well as new values for the `state` enum in the response. * For Deposit Switch, added additional response fields `employer_name`, `employer_id`, `institution_name`, `institution_id`, and `switch_method`. * Updated the list of [ACH partners](https://plaid.com/docs/auth/partnerships/index.html.md) , including adding Alpaca, Astra, and Moov. * For [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , added the fields `include_original_description` and `original_description` in the request and response, respectively. ##### June 2021  * Chase now supports real-time payments and same-day ACH for OAuth-based connections. * Added new Investment account subtypes `life insurance`, `other annuity`, and `other insurance`. * Added new error codes [INSTITUTION\_NOT\_ENABLED\_IN\_ENVIRONMENT](https://plaid.com/docs/errors/institution/index.html.md#institution_not_enabled_in_environment) , `INSTITUTION_NOT_FOUND`, and [PRODUCT\_NOT\_ENABLED](https://plaid.com/docs/errors/item/index.html.md#product_not_enabled) . These codes replace more generic errors that could appear when working with OAuth institutions or API-based institution connections. * Began rolling out improvements to reduce balance latency. * Released a new representation of cryptocurrency, to represent crypto holdings more similarly to investments, rather than foreign currency, in order to match how most popular institutions represent crypto. `institution_price` will now reflect the USD price of the currency, as reported by the institution, and `institution_value` will reflect the value of the holding in USD. `close_price` and `close_price_as_of` will now be populated. `iso_currency_code` will be set to `USD` and `unofficial_currency_code` will be set to `null`. ##### May 2021  * Improved the UI for [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) and enabled it for all "Pay as you go" customers. Customers with a monthly contract who would like to use Instant Match should contact their Plaid account manager. * Removed the requirement to be enabled by Support in order to request an [Asset Report with Insights](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) . * For the Payment Initiation product, launched [Modular Link](https://plaid.com/blog/improving-the-payments-experience) , allowing further UI customization. * For the Payment Initiation product, added an `options` object to [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) to support restricting payments originating from specific accounts. * For the Liabilities product, added a [DEFAULT\_UPDATE webhook](https://plaid.com/docs/api/products/liabilities/index.html.md#default_update) to indicate changes to liabilities accounts. * Made [Item Debugger and improved Institution Status](https://plaid.com/blog/item-debugger-institution-status/) available to 100% of developers. * Added Link [Consent pane customization](https://plaid.com/docs/link/customization/index.html.md#consent-pane-customizations) . * Added the ability to use wildcards to specify a subdomain in an OAuth redirect URI. * Clarified that the following Link onEvent callbacks are stable: `OPEN`, `EXIT`, `HANDOFF`, `SELECT_INSTITUTION`, `ERROR`, but the remaining are informational. ##### April 2021  * In order to support the beta generated client libraries, added the ability to provide `client_id` and `secret` [via headers](https://plaid.com/docs/api/index.html.md#api-protocols-and-headers) instead of as request parameters. * Added the `min_last_updated_datetime` parameter to [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) to handle institutions that do not always provide real-time balances, and added the corresponding `LAST_UPDATED_DATETIME_OUT_OF_RANGE` error. * Removed `last_statement_balance` from the official documentation for [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) , as it was not ever returned. * Fixed the case of submitting an invalid client ID to return an [INVALID\_API\_KEYS](https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_api_keys) error instead of an `INTERNAL_SERVER_ERROR`, in order to match documented behavior. ##### March 2021  * Launched [Plaid Income (beta)](https://plaid.com/income/) for verifying income and employment. * Added the ability to specify an `end_date` for standing orders in the [Payment Initiation](https://plaid.com/docs/payment-initiation/index.html.md) product. * Updated list of active processor partners. * Added [webhook](https://plaid.com/docs/bank-transfers/webhook-events/index.html.md) to notify of new Bank Transfers events. * Added [/sandbox/bank\_transfer/fire\_webhook](https://plaid.com/docs/bank-transfers/reference/index.html.md#sandboxbank_transferfire_webhook) endpoint to test Bank Transfers webhooks. * Added `auth_flow` parameter to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to support Flexible Auth (beta). * Updated the [/payment\_initiation/recipient/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientcreate) endpoint to accept `address.country_code` (preferred) instead of `address.country` (accepted, but deprecated). * Removed the `MATCHED_INSTITUTION_SELECT` transition view event, after consolidating the returning user institution select view. * Added the [SELECT\_BRAND](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-SELECT-BRAND) onEvent callback, after shipping a change that groups institution login portals within the same institution brand. * Stopped sending `IS_MATCHED_USER` and `IS_MATCHED_USER_UI` because these events are duplicates. You should use `MATCHED_CONSENT` and `MATCHED_SELECT_INSTITUTION` to identify when a returning user is recognized and chooses an institution that we pre-matched. ##### February 2021  * Added additional [payment error codes](https://plaid.com/docs/errors/payment/index.html.md) . * Added the UK-only fields [authorized\_datetime](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-transactions-authorized-datetime) and [datetime](https://plaid.com/docs/api/products/transactions/index.html.md#transactions-get-response-transactions-datetime) fields to the `transaction` object, for more detailed information on when the transaction occurred. * Added `update_type` field to the `item` object. This field will be used to support upcoming connectivity improvements to accounts with multi-factor authentication. * Added optional `ssn` and `date_of_birth` fields to the `user` object in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to support upcoming functionality enhancements. * Released an [OpenAPI file](https://github.com/plaid/plaid-openapi) describing the Plaid API. ##### January 2021  * Launched Deposit Switch (beta) for transferring direct deposits from one account to another. * Improved error handling to treat some invalid input errors that were previously treated as 500 errors as `INVALID_INPUT` errors instead. ##### December 2020  * Made Bank Transfers (beta) available for testing in the Development environment. * Added `investments_updates` to the `status` object returned by Institutions endpoints. ##### November 2020  * Removed some internal-only, pre-beta products from appearing in the [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) response. * Restored the `/item/public_token/create` and `/payment_initiation/payment/token/create` endpoints to API version 2020-09-14 to avoid disrupting update mode for end users on older mobile SDKs that do not support Link tokens. These endpoints are still deprecated, and it is recommended you update mobile apps to the latest SDKs as soon as possible. ##### October 2020  * Released API version 2020-09-14. See the [version changelog](https://plaid.com/docs/api/versioning/index.html.md#version-2020-09-14) for details. * Added support for mortgages to [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) . * Released [Bank Transfers](https://plaid.com/docs/bank-transfers/index.html.md) to closed beta. * To improve consistency with other error types, changed the error type for Bank Transfers errors from `BANK_TRANSFER` to `BANK_TRANSFER_ERROR`. * Added the fields `user.phone_number`, `user_email.address`, `user.phone_number_verified_time` and `user.email_address_verified_time` to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to support the new [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) , which allows users a more seamless Link flow. ##### August 2020  * Introduced [standing orders](https://blog.plaid.com/recurring-payments-with-standing-orders/) to [Payment Initiation](https://plaid.com/uk/products/payment-initiation/) for our UK and Europe customers. If applicable, your users will now be able to make recurring scheduled payments with a single authorization. * Expanded access to [full Auth coverage](https://plaid.com/docs/auth/coverage/index.html.md) to more developers. If you would like to use micro-deposit based verification and don't have access to it, contact your Plaid account manager. * Updated Link error messages to provide more actionable instructions for end users, making resolution troubleshooting easier. * Made [account filtering](https://blog.plaid.com/improvements-to-plaid-link-with-account-filtering-and-updated-error-messaging/) available across all our products, so you can configure the Link flow to guide end users in selecting relevant institutions and accounts. ##### July 2020  * Added the [ITEM: USER\_PERMISSION\_REVOKED](https://plaid.com/docs/api/items/index.html.md#user_permission_revoked) webhook, which will notify you when a user contacts Plaid directly to delete their data or change their data sharing preferences with your app. * Released Link tokens, the new preferred way to use Link, replacing the public key. To learn how to migrate your application to use Link tokens, see the [Link token migration guide](https://plaid.com/docs/link/link-token-migration-guide/index.html.md) . ##### June 2020  * Added a new `merchant_name` field to the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) endpoint for the US and Canada, providing clearer and more consistent merchant names for 95% of existing transactions. * Added the [PAYMENT\_INITIATION:PAYMENT\_STATUS\_UPDATE](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_status_update) webhook, which pushes instant notifications when payment status changes for the [UK Payment Initiation product](https://plaid.com/uk/products/payment-initiation/) . * Added the ability to create payment recipients via sort codes and account numbers, not just IBANs. ##### May 2020  * We launched a new open finance platform called [Plaid Exchange](https://blog.plaid.com/introducing-plaid-exchange/) that enables financial institutions to build a consumer-permissioned data access strategy and strengthen the ability of end users to reliably access their financial data. ##### April 2020  * Launched [Payment Initiation](https://plaid.com/uk/products/payment-initiation/) in the UK, which offers an easy way for users to fund their accounts, make purchases, and pay invoices—all from their favorite apps or websites. ##### March 2020  * Added the ability to [filter by account\_subtype](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , allowing you to further optimize the Link flow. * Added the `HOLDINGS: DEFAULT_UPDATE` and `INVESTMENT_TRANSACTIONS: DEFAULT_UPDATE` webhooks, which will fire each time data has successfully refreshed for Holdings and Investments Transactions. ##### February 2020  * Added [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) , which enables you to pull a user's transactions on demand. * Added [/webhook\_verification\_key/get](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md#get-webhook-verification-key) , which allows you to verify the authenticity of incoming webhooks. ##### January 2020  * Added `store_number`, `authorized_date`, and `payment_channel` to the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) response. * Added the `investment_transactions.subtypes` field to provide more granular detail about the tax, performance, and fee impact of investments transactions. ##### November 2019  * Added the `status.investments.last_successful_update` and `status.investments.last_failed_update` fields to the data returned by [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) . * Launched official support for Link on React Native with a new [SDK](https://github.com/plaid/react-native-plaid-link-sdk) , bringing unified support to React Native apps. ##### October 2019  * Added the `status.item_logins.breakdown` data to [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) and the Developer Dashboard. * Added the `routing_numbers` field to the Institutions object. You can also filter institutions via the `options.routing_numbers` field in each Institutions API endpoint. ##### September 2019  * Added support for [credit card details](https://blog.plaid.com/liabilities-credit-cards) to the Liabilities product. * Added Canada-specific account subtypes, including RRSP, RESP, and TFSA, to the Investments product. ##### August 2019  * Among numerous other improvements to Liabilities, such as expanded data access, added a new `loan_type`: `cancelled` to the Liabilities product. ##### July 2019  * We launched [Liabilities](https://blog.plaid.com/liabilities/) , which enables developers to access a feed of standardized student loan details from the largest U.S. servicers including Navient, Nelnet, FedLoan, Great Lakes, and many more. ##### June 2019  * Launched [Investments](https://blog.plaid.com/investments/) , which allows developers, fintech apps, and financial institutions to create a holistic view of their customers' investments. * Added the `status.transactions_updates` field, exposing Transactions health to both the [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) endpoint and the Dashboard. ##### May 2019  * We enhanced the [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) endpoint to now return [account-level identity information](https://plaid.com/docs/api/products/identity/index.html.md#identityget) within the `accounts` object where available. * We released [API version 2019.05.29](https://plaid.com/docs/api/versioning/index.html.md#version-2019-05-29) to enable European institution coverage and provide nomenclature and schema updates required by Identity and future products. ##### March 2019  * We updated the [institutions endpoints](https://plaid.com/docs/api/institutions/index.html.md) so you can now retrieve bank logos, colors, and website URLs to use to customize your in-app experience. * We enabled triggering and testing of webhooks on demand via the new [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) endpoint. ##### February 2019  * We launched [new features for Auth](https://blog.plaid.com/new-auth/) , enabling developers to authenticate accounts from any bank or credit union in the U.S. Link automatically guides end-users to the best way to authenticate their account based on the bank they select. ##### November 2018  * Added a new [Insights](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) feature, which provides cleaned and categorized transaction data in an Asset Report. In addition to transaction categories, lenders will be able to retrieve merchant names and locations for transactions to use in building risk models. * Improved the Link experience by informing users about connectivity issues with banks before connecting their account. When banks are experiencing significant issues, users will temporarily be directed to connect their account at a different bank to reduce frustration and drop-off during the onboarding process. ##### September 2018  * We added the [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) endpoint, so you can create a new Asset Report with the latest account balances and transactions for a borrower, based on the old report. ##### August 2018  * We added [account filtering](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) , which gives you the ability to exclude unnecessary accounts from appearing in an Asset Report. ##### June 2018  * Added historical account balances to the PDF version of Asset Reports, bringing them closer in line with the core JSON endpoint. ##### May 2018  * We released the [2018-05-22 version](https://plaid.com/docs/api/versioning/index.html.md#version-2018-05-22) of the Plaid API. * We enabled distinct API secrets [to now be set](https://blog.plaid.com/api-secrets/) for the Sandbox, Development, and Production environments. * Added the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) endpoint, which enables the creation of Items in the Sandbox environment directly via the API (without Link). ##### April 2018  * Officially launched the [Assets](https://plaid.com/products/assets/) product. Assets is approved by Fannie Mae for [Day 1 Certainty™](https://www.fanniemae.com/singlefamily/day-1-certainty) asset verification. ##### March 2018  * Rolled out several Assets features, including webhooks for Asset Report generation and full support for Audit Copy token generation and Fannie Mae's Day 1 Certainty™ program, while improving existing features like pending transaction support in PDF reports. ##### February 2018  * Released Assets as a beta product. --- # Consumer Report (by Plaid Check) - Implementation | Plaid Docs Add Consumer Report to your app  ================================ #### Onboard your users to Plaid Check to generate cash flow insights  This guide will walk you through onboarding your users to Plaid Check, so you can generate cash flow insights for your customers by creating a Consumer Report. This is designed as a granular, step-by-step walkthrough showing one option for a simple Plaid Check integration for customers new to Plaid. Plaid also offers a [no-code integration option](https://plaid.com/docs/check/index.html.md#no-code-integration-with-the-credit-dashboard) and a [high-level integration overview](https://plaid.com/docs/check/index.html.md#standard-integration-flow) . If you are migrating to Plaid Check Consumer Reports from a different Plaid product, see the corresponding migration guide: [Migrate from Assets](https://plaid.com/docs/check/migrate-from-assets/index.html.md) , [Migrate from Income](https://plaid.com/docs/check/migrate-from-income/index.html.md) , or [Migrate from Transactions](https://plaid.com/docs/check/migrate-from-transactions/index.html.md) . #### Install and initialize Plaid libraries  You can use our official server-side client libraries to connect to the Plaid Check API from your application: ```node // Install via npm npm install --save plaid ``` ```bash ## Not applicable with curl calls ``` ```ruby # Available as a gem gem install plaid ``` ```java /* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ implementation "com.plaid:plaid-java:{VERSION}" /* For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ com.plaid plaid-java {VERSION} ``` ```python # Install through pip, only supports Python 3 pip install --upgrade plaid-python ``` ```go go get github.com/plaid/plaid-go ``` After you've installed these client libraries, initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls. ```node // Using Express const express = require('express'); const app = express(); app.use(express.json()); const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const client = new PlaidApi(configuration); ``` ```bash ## Not applicable with curl calls ``` ```ruby require 'sinatra' require 'plaid' set :port, ENV['APP_PORT'] || 8000 configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) ``` ```java import java.net.*; import java.io.*; import retrofit2.Response; import java.util.Arrays; import com.sun.net.httpserver.*; import com.plaid.client.ApiClient; import com.plaid.client.request.PlaidApi; public class PlaidExample { private static final String CLIENT_ID = System.getenv("PLAID_CLIENT_ID"); private static final String SECRET = System.getenv("PLAID_SECRET"); public static void main(String[] args) { HttpServer server = HttpServer.create( new InetSocketAddress("localhost", 8000), 0); server.createContext("/create_link_token", new GetLinkToken()); server.setExecutor(null); server.start(); } // Additional server code goes here } ``` ```python import plaid from plaid.api import plaid_api from flask import Flask from flask import render_template from flask import request from flask import jsonify app = Flask(name) configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Additional server code goes here if __name__ == "__main__": app.run(port=8000) ``` ```go import ( "context" "net/http" "os" "github.com/gin-gonic/gin" "github.com/plaid/plaid-go/v3/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) func main() { r := gin.Default() // Server endpoints would be declared here // e.g. r.POST("/create_link_token", createLinkToken) r.POST("/create_link_token", createLinkToken) err := r.Run(":8000") if err != nil { panic("unable to start server") } } ``` #### Create a user  Your next step is to create a `user_id` that will represent the end user. To create a `user_id`, make a call to the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint. This endpoint requires a unique `client_user_id` value to represent the current user. Typically, this value is the same identifier you're using in your own application to represent the currently signed-in user. In addition, you will need to pass in an `identity` object to use Plaid Check products for this user. In this field, you should pass in user identity data that has been provided by your user for consumer report purposes. At minimum, the following fields must be provided: * `name` * `date_of_birth` * `emails` * `phone_numbers` * `addresses` At least one email, phone number, and address must be designated as `primary`. If you intend to share the report with a GSE (Government-Sponsored Entity) such as Fannie or Freddie, the full SSN is also required via the `id_numbers` field. For all use cases, providing at least a partial SSN is highly recommended, since it improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. The [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint will return a randomly generated string for the `user_id`. Make sure to save it. You send the `user_id` to Plaid Check to generate reports, and Plaid Check will use it to refer to this user when it sends you a webhook. Depending on your application, you might wish to create this `user_id` as soon as your user creates an account, or wait until shortly before your application would want to generate a report for this user. #### Create a Link token  Link is a client side UI widget that provides a secure, elegant flow to guide your users through the process of connecting Plaid Check with their financial institutions. Before initializing Link, you will need to create a `link_token`. A `link_token` is a short-lived, single-use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint from your server. When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , you'll include an object telling Plaid Check about your application as well as how to customize the Link experience. In addition to the required parameters, you will need to provide the following: * For `user_id`, provide the `user_id` you created in the previous step. * For `products`, pass in `cra_base_report`, plus any additional Plaid Check products you wish to use (`cra_income_insights`, `cra_partner_insights`, and/or `cra_network_insights`), along with any additional Plaid Inc. products you are using. Note that Plaid Check products can't be used in the same Link flow with Income or Assets. * Provide a `webhook` URL with an endpoint where you can receive webhooks from Plaid Check. Plaid Check will contact this endpoint when your report is ready. * Include the appropriate options for the products you are using in the `cra_options` object. * Include a `consumer_report_permissible_purpose` parameter specifying your purpose for generating an Consumer Report. * On mobile, specify the `redirect_uri` and/or `android_package_name` fields as necessary, per the relevant [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform. Send the `link_token` you get back in the response to your client application. ```node const request: LinkTokenCreateRequest = { loading_sample: true }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```python request = LinkTokenCreateRequest( loading_sample=True ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "loading_sample": true }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { loading_sample: true } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .loadingSample(true); Response response = client .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```go request := plaid.NewLinkTokenCreateRequest( "Sample App App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetLoadingSample(true) linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := linkTokenCreateResp.GetLinkToken(); ``` ##### Using Plaid Check products alongside Plaid products  If you wish to use Plaid Inc. products (Transactions, Auth, etc.) alongside Plaid Check products, you can. You can just add those products to the appropriate products array when sending a request to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Link will take the user through a hybrid flow, where we establish connections to both Plaid Check and Plaid Inc. at the same time. One exception is that you cannot use the Plaid Inc. Income or Assets in the same session as a Plaid Check product. Instead, you should use the similar CRA Income Insights or CRA Base Consumer Report products. #### Initialize Link  Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the appropriate section in the [Link documentation](https://plaid.com/docs/link/index.html.md) . To integrate with Embedded Link, visit these [integration steps](https://plaid.com/docs/link/embedded-institution-search/index.html.md#integration-steps) . ##### Install the Link library  You will need to install the Link JavaScript library in order to use Link in your web application. index.html ```html Extend my Credit ``` ##### Configure the client-side Link handler  To run Link, you'll first need to retrieve the `link_token` from the server as described above. Then call `Plaid.create()`, passing along that token alongside other callbacks you might want to define. This will return a handler that has an `open` method. Call that method to open up the Link UI and start the connection process. app.js ```javascript const linkHandler = Plaid.create({ token: link_token_from_previous_step, onSuccess: (public_token, metadata) => { // Typically, you'd exchange the public_token for an access token. // You won't do that with Plaid Check products. }, onExit: (err, metadata) => { // Optionally capture when your user exited the Link flow. // Storing this information can be helpful for support. }, onEvent: (eventName, metadata) => { // Optionally capture Link flow events, streamed through // this callback as your users connect an Item to Plaid Check. }, }); linkHandler.open(); ``` If you've used Link in the past with products created by Plaid, you're probably used to taking the `public_token` received from Link and exchanging it on your server for a persistent `access_token`. That is not necessary for products created by Plaid Check, and is only necessary if you are using the hybrid flow, where you are using Plaid Inc. products (Transactions, Auth, etc.) alongside Plaid Check products. #### Generate a report  Plaid Check will start generating the Consumer Report for your user once they have completed the Link process. Consumer Reports expire 24 hours after they have been created. After that point, you can [generate a new report](https://plaid.com/docs/check/add-to-app/index.html.md#generating-updated-reports) by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) , passing along the `user_id` you created earlier. #### Listen for webhooks  After a user has finished using Link, it may take some time before the Consumer Report is available for you to retrieve. Listen for the `USER_CHECK_REPORT_READY` webhook to know when it is safe to request the appropriate set of product data. webhookServer.js ```javascript app.post('/server/receive_webhook', async (req, res, next) => { const product = req.body.webhook_type; const code = req.body.webhook_code; if (product === 'CHECK_REPORT') { if (code === 'USER_CHECK_REPORT_READY') { const userId = req.body.user_id; // It is now okay to start fetching Consumer Report data for this user fetch_cra_report_for_user(userId); } else if (code === 'USER_CHECK_REPORT_FAILED') { const userId = req.body.user_id; // Handle this error appropriately report_error_with_generating_report(userId); } } // Handle other types of webhooks }); ``` #### Request product data  Once Plaid Check has informed you that your report is ready, you can use one of the Plaid Check product endpoints ([/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , or [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) ) to retrieve the appropriate cash flow insights. You can attempt to retrieve any type of product data, even if you didn't initialize it in the `products` array when you called [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . However, retrieving new products might incur some latency as Plaid Check generates the new insight data. Reports expire 24 hours after they have been created (either through a Link session that included the `consumer_report_permissible_purpose` parameter or through a [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) call). If you don't fetch any product data on top of this report within that time frame, you will need to generate a new Consumer Report. #### Handling multiple institutions  If you would like your Consumer Report to include information from multiple institutions, the best way is to add the `enable_multi_item_link: true` flag to your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call to enable [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) . Your user will then have the option to connect to as many institutions as they wish during their Link session, and the generated report will contain data from each institution that the user connects to. ##### Adding institutions after the initial Link session  If your user wants to add additional institutions _after_ their initial Link session, you may do so by once again generating a Link token (using the same `user_id` as before, and including at least one Plaid Check product in the products array), and opening a new Link session on the client. Plaid Check will start generating a new report for your user when they are done with a Link session. However, this report will _only_ contain data from the institution that the user connected to during this most recent Link session. When the user is done, re-generate your Consumer Report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) as described in the [Generating updated reports](https://plaid.com/docs/check/add-to-app/index.html.md#generating-updated-reports) section below. #### Testing in Sandbox  Because Consumer Report information is heavily dependent on income data, Plaid recommends using the test accounts designed for producing realistic looking income data, such as `user_bank_income` (with the password `{}`). The basic Sandbox credentials (`user_good`/`pass_good`) do not return good income data. Plaid also has additional test users to represent different levels of creditworthiness. For details, see [Credit and Income testing credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#credit-and-income-testing-credentials) . When using special Sandbox test credentials (such as `user_bank_income` / `{}`), use a non-OAuth test institution, such as First Platypus Bank (ins\_109508) or many smaller community banks. Special test credentials may be ignored when using the Sandbox Link OAuth flow. To use a [Sandbox custom user](https://plaid.com/docs/sandbox/user-custom/index.html.md) with Plaid Check, click "add new account" rather than using one of the existing banks. Using an existing bank in the Plaid Passport flow will skip the ability to enter a custom username. ##### Testing Cash Flow Updates  After calling [/cra/monitoring\_insights/subscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightssubscribe) , use the [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) endpoint to manually trigger an update for Cash Flow Updates (Monitoring) in the Sandbox environment. To avoid unexpected behavior when passing `LOW_BALANCE_DETECTED` in the `webhook_codes` field of the [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) request body, use the default custom Sandbox user `user_good`. ##### Testing Income Insights  Use the [Sandbox credit testing credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#credit-and-income-testing-credentials) with a non-OAuth test institution, such as First Platypus Bank, for more realistic and valid data. To customize the employer name during testing, you can test with a custom Sandbox user, following the custom Sandbox user [documentation](https://plaid.com/docs/sandbox/user-custom/index.html.md) and [examples](https://github.com/plaid/sandbox-custom-users/) . When creating an income transaction for this user: * The `amount` must be negative, so that the transaction will represent income. * `date_transacted` and `date_posted` must fall within the `cra_options.days_requested` range of the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. * the `description` field must contain the desired employer name, followed by `Direct Dep`. The example transaction below will generate an income stream with the employer name `Weyland-Yutani`. Sample income transaction for testing employer name ```json { "date_transacted": "2025-08-01", "date_posted": "2025-08-03", "amount": -5500, "description": "Weyland-Yutani Direct Dep", "currency": "USD" } ``` #### Generating updated reports  If, after some time has passed, you wish to generate a new report with updated data (or a user has connected additional institutions), you can do so by performing the following steps: 1. Generate the new report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) with the same `user_id` you used earlier. 2. Wait for the `USER_CHECK_REPORT_READY` webhook. 3. Once you have received the webhook, use one of the Plaid Check product endpoints ([/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , or [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) ) to retrieve the corresponding product data. --- # Consumer Report (by Plaid Check) - Introduction | Plaid Docs Introduction to Consumer Report   ================================= #### Use Consumer Report for smarter credit and lending decisions powered by Plaid Check  Get started with Consumer Report [API Reference](https://plaid.com/docs/api/products/check/index.html.md) [Request Access](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) [Quickstart](https://github.com/plaid/credit-quickstart) [Demo](https://plaid.coastdemo.com/share/67ed96db47d17b02bdfc4a88?zoom=100) #### Overview  Evaluate a consumer's income, assets, employment, and financial stability in seconds based on insights and attributes derived from cash flow data. Get comprehensive, up-to-date bank account data to grow qualified borrowers, manage risk, and make credit and verification decisions with confidence - all through a single, high-converting UX. To see a full financial picture, Consumer Report, offered through Plaid Check (Plaid's CRA subsidiary), provides three different product bundles, with two optional add-ons. Plaid Check products are available only to US entities and can be used only to evaluate US consumers. Plaid Check includes a variety of different modules, broken into three use cases: Income, Home Lending, and Underwriting. In addition, two modules are available as add-ons for any of the three use-case bundles. #### Income modules  Income modules are designed for customers performing income or employment verification. ##### Base Report  Provides comprehensive bank account and cash flow data: See up to 24 months of consumer-permissioned bank account data (including account holder identity) along with categorized inflows and outflows. Get account-based attributes like balance averages and trends, as well as indicators of whether this is the borrower's primary account based on transaction frequency. ##### Income Insights  Get details on over a dozen categorized income streams along with ready-made, model-driven attributes like historical gross and net income to streamline debt-to-income calculations and income verification. Assess financial stability with insights like forecasted income, employer name, income frequency, and predicted next payment date. #### Underwriting modules  Underwriting modules are designed for customers performing non-mortgage underwriting, such as BNPL, personal lending, or second-look underwriting. ##### Base Report  Provides comprehensive bank account and cash flow data: See up to 24 months of consumer-permissioned bank account data (including account holder identity) along with categorized inflows and outflows. Get account-based attributes like balance averages and trends, as well as indicators of whether this is the borrower's primary account based on transaction frequency. ##### LendScore (beta)  Based on data from both Cash Flow Insights and Network Insights, the Plaid LendScore is a score from 1-99, indicating how likely a borrower is to default over the next 12 months, across a broad range of credit products; a higher score indicates greater likelihood of repayment. The LendScore is a single, market-ready score that lenders can use to better understand the creditworthiness of applicants by layering in ability to pay and behavioral insights. LendScore also returns the top five reasons the score is not higher, for use in adverse action notices. ##### Network Insights (beta)  Receive insights based on a user's connection history, including for services that aren't consistently reported to traditional credit bureaus, such as rent, buy-now-pay-later, cash advances, and earned wage access applications. With credit insights powered by the Plaid Network, lenders receive differentiated risk signals that are complementary to traditional credit and cash flow. ##### Cash Flow Insights (beta)  Receive aggregated transaction data across all permissioned accounts. This data can be used for credit decisioning and forms the basis of the Plaid LendScore. It also includes measures of volatility across income and expenditure categories, allowing lenders to better understand how an applicant is managing their finances. #### Home Lending modules  Home Lending modules are designed for customers performing home lending underwriting. ##### Home Lending Report  Designed specifically for home lending, Home Lending Report provides an FCRA-compliant asset verification report approved for use with Fannie Mae Day 1 Certainty and Freddie Mac's Loan Product Advisor® (LPA®) Asset and Income Modeler (AIM). With Home Lending Report, lenders can validate asset balances, account ownership, and transaction behavior; submit reports to GSEs for rep and warrant relief; refresh reports for employment verification pre-close; and replace document uploads with a single Plaid Link session. To create a Home Lending Report and (optionally) share it with a GSE, follow the [Home Lending integration flow](https://plaid.com/docs/check/index.html.md#home-lending-integration-flow) . #### Add-on modules  The following modules are available as add-ons for any of the above use cases. ##### Partner Insights  For scores and attributes: Get off-the-shelf cash flow risk scores based on de-identified deposit account data. Offered through [Prism Data](https://prismdata.com) , these scores and attributes assess a consumer's credit default risk and are available through a single integration and API call. ##### Cash Flow Updates (beta)  Receive regular updates about changes to cash flow. See how income and loan exposure have changed for a borrower over time to improve post-decision servicing. #### Integration overview  If you already use one of Plaid's other products, see the product-specific migration guides for [Assets](https://plaid.com/docs/check/migrate-from-assets/index.html.md) , [Income](https://plaid.com/docs/check/migrate-from-income/index.html.md) , or [Transactions](https://plaid.com/docs/check/migrate-from-transactions/index.html.md) . ##### Standard integration flow  Below is a high-level integration overview. For detailed step-by-step instructions with sample code, see [Implementation](https://plaid.com/docs/check/add-to-app/index.html.md) . The flow below describes the latest integration pattern for Plaid Check Consumer Reports. If you are an existing customer who integrated before December 10, 2025, your API calls have a slightly different interface. For details on the differences, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . To migrate your existing integration, see the [migration guide](https://plaid.com/docs/api/users/migrate-to-new-user-apis/index.html.md) . 1. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) to create a `user_id`. You must include an `identity` object when calling [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . At minimum, the following fields must be provided and non-empty: `name`, `date_of_birth`, `emails`, `phone_numbers`, and `addresses` (with at least one email address, phone number, and address designated as `primary`). If you intend to share the report with a GSE (Government-Sponsored Entity) such as Fannie or Freddie, the full SSN is also required via the `id_numbers` field. Providing at least a partial SSN via `id_numbers` is also highly recommended for all use cases since it improves the accuracy of matching user records during compliance processes. The user creation step will only need to be done once per end user. 2. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following: * For `user_id`, provide the `user_id` you created in the previous step. * For `products`, pass in `cra_base_report`, plus any additional Plaid Check products you wish to use (`cra_income_insights`, `cra_partner_insights`, and/or `cra_network_insights`), along with any additional Plaid Inc. products you are using. Note that Plaid Check products can't be used in the same Link flow with Income or Assets. * Provide a `webhook` URL with an endpoint where you can receive webhooks from Plaid Check. Plaid Check will contact this endpoint when your reports are ready. * Include the appropriate options for the products you are using in the `cra_options` object, including the required [days\_requested](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-cra-options-days-requested) field. * Include a `consumer_report_permissible_purpose` specifying your purpose for generating an insights report. * On mobile, specify the `redirect_uri` and/or `android_package_name` fields as necessary, per the relevant [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform. * If you already have an existing Item and need to add Plaid Check to the Item, provide the Item's `access_token` in the `options.access_token` field. Otherwise, omit the `access_token` field in your request. 3. On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . 4. Launch Link with the Link token and send the user through the Link flow. Once they have completed the flow and the report is ready, you will receive a [USER\_CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_ready) webhook. 5. Upon receiving the `USER_CHECK_REPORT_READY` webhook, fetch the report data using an endpoint such as [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) , [/cra/check\_report/network\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportnetwork_insightsget) , or [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) . This data must be fetched within 24 hours of report creation. 6. (Optional) To refresh a Consumer Report with new data, call [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) to refresh the report. Upon refresh, a new `USER_CHECK_REPORT_READY` webhook will fire and you can repeat the step above. ##### Home Lending integration flow  Below is a variation on the standard flow with a focus on home lending-related use cases and sharing reports with a GSE. 1. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) to create a `user_id`. You must include an `identity` object when calling [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . The user creation step will only need to be done once per end user. * Make sure to include the user's full SSN, as it is required for GSE integrations. 2. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following: * Set [gse\_options.report\_types](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-cra-options-base-report-gse-options-report-types) to contain `VOA`. * For `user_id`, provide the `user_id` you created in the previous step. * For `products`, pass in `cra_base_report`. * Provide a `webhook` URL with an endpoint where you can receive webhooks from Plaid Check. Plaid Check will contact this endpoint when your reports are ready. * Include the appropriate options for the products you are using in the `cra_options` object, including the required [days\_requested](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-cra-options-days-requested) field. * Include a `consumer_report_permissible_purpose` specifying your purpose for generating an insights report. * On mobile, specify the `redirect_uri` and/or `android_package_name` fields as necessary, per the relevant [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform. 3. On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . 4. Launch Link with the Link token and send the user through the Link flow. Once they have completed the flow and the report is ready, you will receive a [CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#check_report_ready) webhook. 5. Upon receiving the `CHECK_REPORT_READY` webhook, fetch a Home Lending Report using [/cra/check\_report/verification/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationget) or a PDF copy using [/cra/check\_report/verification/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationpdfget) . This data must be fetched within 24 hours of report creation. 6. When GSE options are specified, the Home Lending Report response will contain a `gse_reference_id`, which is an OAuth token that can be used by the GSE partner you want to share report data with to access the report. You may also use the [/oauth/token](https://plaid.com/docs/api/oauth/index.html.md#oauthtoken) endpoint to create a sharing token. For more details, see [Sharing Consumer Report data with partners](https://plaid.com/docs/check/oauth-sharing/index.html.md) . 7. Send the OAuth token to your GSE partner and continue through their flow. 8. (Optional) To refresh a Consumer Report with new data, call [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) to refresh the report. Upon refresh, a new `CHECK_REPORT_READY` webhook will fire and you can repeat step 5 above. * After refreshing the report, to share the refreshed report with a GSE, you must create a new sharing token by repeating steps 6-7 above. Example /link/token/create call for home lending use case ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user": { "client_user_id": "user-abc", "email_address": "user@example.com" }, "user_id": "usr_9nSp2KuZ2x4JDw"", "products": ["cra_base_report"], "consumer_report_permissible_purpose": "ACCOUNT_REVIEW_CREDIT", "cra_options": { "days_requested": 365, "base_report": { "gse_options": { "report_types": ["voa"] } } }, "gse_options": { "report_type": ["VOA"] }, "client_name": "The Loan Arranger", "language": "en", "country_codes": ["US"], "webhook": "https://sample-web-hook.com" }' ``` ##### Cash Flow Updates integration  To receive Cash Flow Updates (beta) on a Plaid Check-enabled user, follow the steps in the [Standard integration flow](https://plaid.com/docs/check/index.html.md#standard-integration-flow) , then perform the following additional steps: 1. Call [/cra/monitoring\_insights/subscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightssubscribe) , passing in the `user_id`. 2. Listen for the [CASH\_FLOW\_INSIGHTS: CASH\_FLOW\_INSIGHTS\_UPDATED](https://plaid.com/docs/api/products/check/index.html.md#cash_flow_insights_updated) webhook, which will be sent between one and four times a day for a user's Item. 3. Call [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) to retrieve the updated insights. 4. (Optional) To stop receiving `CASH_FLOW_INSIGHTS_UPDATED` webhooks for a user, call [/cra/monitoring\_insights/unsubscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsunsubscribe) . ##### No-code integration with the Credit Dashboard  The Credit Dashboard is currently in beta. To request access, contact your account manager. Consumer Report data is available via a no-code integration through the [Credit Dashboard](https://dashboard.plaid.com/credit) . You can fill out a form with information about your end user, such as their name, email address, address, and phone number; and indicate your basis for processing this data and how much history you would like to collect. Plaid will then generate a hyperlink that can be used to launch a Plaid-hosted Link session. Plaid can email the link directly to your user (Production only, not available in Sandbox), or you can send it to them yourself. After the end user successfully completes the Link session, their data will be available in the Dashboard for you to view, archive, or delete. The data shown will be the same data returned by a regular Consumer Report API call, in a user-friendly web-based session. (An image of "Example dashboard credit report for end user, showing forecasted annual and monthly incomes. Income sources listed with types and frequency.") Once you are enabled for the Credit Dashboard, all new sessions going forward, including ones created via the API, will be displayed in the Dashboard. Data from Link sessions created via the Credit Dashboard cannot be accessed via the Plaid API. If you require programmatic access to data, use the code-based [Standard integration flow](https://plaid.com/docs/check/index.html.md#standard-integration-flow) instead. ##### Integrating with other Plaid products  If you are using other Plaid Inc. products, note that the `account_id` returned in API responses from endpoints prefixed with `/cra/` will not match the `account_id` returned in responses from non-CRA Plaid endpoints. You can map accounts between Plaid CRA endpoints and Plaid endpoints by matching other fields such as `mask`, account `type` and `subtype`, and `institution_id`. If all of these fields match, and the accounts are associated with the same user in your records, the accounts are very likely the same. ##### Sharing reports with partners via OAuth  To share a report with a partner such as Experian, Fannie Mae, or Freddie Mac, see [Share reports with partners](https://plaid.com/docs/check/oauth-sharing/index.html.md) . #### Testing Consumer Report  Access to Consumer Report in Sandbox is not granted by default. To request access, [contact sales](https://plaid.com/check/income-and-underwriting/#contact-form) or, for existing Plaid customers, contact your account manager or submit a [product access request](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) . Customers with [Production access to Consumer Report](https://dashboard.plaid.com/settings/team/product) will also automatically be granted Sandbox access. For details on how to test specific scenarios, including multiple income streams, specific employer names, or cash flow update events, see [Add Consumer Report to your App: Testing in Sandbox](https://plaid.com/docs/check/add-to-app/index.html.md#testing-in-sandbox) . ##### Testing Income Insights  Use the [Sandbox credit testing credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#credit-and-income-testing-credentials) with a non-OAuth test institution, such as First Platypus Bank, for more realistic and valid data. To customize the employer name during testing, you can test with a custom Sandbox user, following the custom Sandbox user [documentation](https://plaid.com/docs/sandbox/user-custom/index.html.md) and [examples](https://github.com/plaid/sandbox-custom-users/) . When creating an income transaction for this user: * The `amount` must be negative, so that the transaction will represent income. * `date_transacted` and `date_posted` must fall within the `cra_options.days_requested` range of the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. * the `description` field must contain the desired employer name, followed by `Direct Dep`. The example transaction below will generate an income stream with the employer name `Weyland-Yutani`. Sample income transaction for testing employer name ```json { "date_transacted": "2025-08-01", "date_posted": "2025-08-03", "amount": -5500, "description": "Weyland-Yutani Direct Dep", "currency": "USD" }, ``` #### Billing  For details, see [Plaid Check fee model](https://plaid.com/docs/account/billing/index.html.md#plaid-check-fee-model) . #### Next steps  To get started building with Plaid Check, see [Add Consumer Report to your App](https://plaid.com/docs/check/add-to-app/index.html.md) . If you're migrating from another product, see the [Assets migration guide](https://plaid.com/docs/check/migrate-from-assets/index.html.md) , [Income migration guide](https://plaid.com/docs/check/migrate-from-income/index.html.md) , or [Transactions migration guide](https://plaid.com/docs/check/migrate-from-transactions/index.html.md) . If you're ready to launch to Production, see the Launch Center. #### Launch Center  See next steps to launch in Production [Launch](https://dashboard.plaid.com/developers/launch-center) --- # Consumer Report (by Plaid Check) - Migrate from Assets | Plaid Docs Migrate from Asset Reports to Base Reports  =========================================== #### Migrate to Base Reports to unlock access to the Consumer Report  This guide will walk you through how to migrate from generating Asset Reports with Plaid's [Assets](https://plaid.com/products/assets/) product to generating Base Reports with Plaid Check's [Consumer Report](https://plaid.com/check/income-and-underwriting/) product. #### Prerequisites  1. To use Consumer Report, it is strongly recommended to update your Plaid client library to the latest version. The minimum required versions for new Consumer Report integrations are: * Python: 38.0.0 * Go: 41.0.0 * Java: 39.0.0 * Node: 41.0.0 * Ruby: 45.0.0 2. [Confirm](https://dashboard.plaid.com/settings/team/products) that you have access to all required Plaid Check products in the Production environment. If you don't have access to Plaid Check, [request access via the Dashboard](https://dashboard.plaid.com/overview/request-products) . In order to migrate from Assets to Plaid Consumer Report, your end users must be in the US and you must be on a custom plan. #### Changes to Plaid Link initialization  When using Plaid Check products, you must create a user prior to sending the user through Link, and you must initialize Link with the resulting `user_id`. This allows Plaid to associate multiple Items with a single user. 1. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) prior to creating a Link token * Include information about your user in the `identity` object. At minimum, the following fields must be provided and non-empty: `name`, `emails`, `phone_numbers`, and `addresses`. If you intend to share the report with a GSE (Government-Sponsored Entity) such as Fannie or Freddie, the full SSN is also required via the `id_numbers` field. For all use cases, providing at least a partial SSN is highly recommended, since it improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. * Store the `user_id` in your database 2. Update your call to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) * Include the `user_id` string from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) * Replace the `assets` product string with `cra_base_report` in the `products` array * Add a `cra_options` object and specify your desired `days_requested` * Include a `consumer_report_permissible_purpose` 3. (Optional) Unlike Assets, by default, Plaid Check includes only one linked Item per Report. To include multiple Items in a single Consumer Report, set `enable_multi_item_link` to `true` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request. ```node const request: LinkTokenCreateRequest = { loading_sample: true }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```python request = LinkTokenCreateRequest( loading_sample=True ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "loading_sample": true }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { loading_sample: true } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .loadingSample(true); Response response = client .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```go request := plaid.NewLinkTokenCreateRequest( "Sample App App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetLoadingSample(true) linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := linkTokenCreateResp.GetLinkToken(); ``` For more details, see the Plaid Check [Implementation guide](https://plaid.com/docs/check/add-to-app/index.html.md) . ##### Adding Consumer Report to existing Items  To enable an existing Assets-enabled Item for Consumer Report, call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) as described above, but include the Item's `access_token` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . When Link is launched, the end user will go through the Consumer Report consent flow, and on successful completion of the flow, the Item will be enabled for Consumer Report. #### Changes to post-Link integration  Update your webhook listeners to listen for the new `USER_CHECK_REPORT_READY` and `USER_CHECK_REPORT_FAILED` webhooks. * Upon receiving a `USER_CHECK_REPORT_READY` webhook, you should call [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , along with any other Consumer Report product endpoints that you would like to use. * Upon receiving a `USER_CHECK_REPORT_FAILED` webhook, you should call [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) to determine why Items are in a bad state. If appropriate, send the user through [Update Mode](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode) to repair them. If you plan to continue using other Plaid Inc. products, such as [Auth](https://plaid.com/products/auth/) or [Balance](https://plaid.com/products/balance/) , you should continue to retrieve the public token and exchange it for an access token. If not, you no longer need to obtain an access token. #### Mapping API responses  Asset Reports and Base Reports have similar but not identical schemas. This [Google Sheet](https://docs.google.com/spreadsheets/d/1toj71Afemtu0rSjgh7AAGgBcZC7U0vYXKCDvKSSWTls/edit?usp=sharing) highlights their differences. If you are using other Plaid Inc. products, note that the `account_id` returned in API responses from endpoints prefixed with `/cra/` will not match the `account_id` returned in responses from non-CRA Plaid endpoints. --- # Consumer Report (by Plaid Check) - Migrate from Income | Plaid Docs Migrate from Bank Income to Plaid Consumer Report  ================================================== #### Switch to CRA Income Insights for model-driven income attributes and FCRA compliance  This guide will walk you through how to migrate from accessing bank data with Plaid's [Bank Income](https://plaid.com/docs/income/index.html.md) product to generating Income Insights Reports with Plaid Check's Consumer Reports. The CRA Income Insights Report offers model-driven attributes such as historical gross and net income, facilitating streamlined debt-to-income calculations and income verification. It enables assessment of financial stability through insights like forecasted income, employer name, income frequency, and predicted next payment date. #### Advantages of Plaid Consumer Report  Bank Income gives you net income data from both irregular or gig income and W-2 income. The CRA Income Insights Report enhances this by: * Providing FCRA-compliant insights * Bundling income calculations (historical average income, forecasted income, predicted next payment date) in a single report Upgrading to Plaid Consumer Report is recommended for all Bank Income customers whose end users are based in the US. (CRA Income Insights is not available for end users outside the US.) Income Insights does not replace Document Income or Payroll Income. Plaid Check products can't be used in the same Link flow as Plaid Inc. credit products such as Plaid Document Income, Payroll Income, Assets, or Statements. If you want to continue using any of those products, create separate [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) requests: one for Plaid Check products, and one for the Plaid Inc. credit products. Non-credit Plaid products, such as Balance and Auth, can continue to be used in the same Link flow as Plaid Check products, and do not require any special changes to your integration. #### Prerequisites  1. To use Consumer Report, it is strongly recommended to update your Plaid client library to the latest version. The minimum required versions for new Consumer Report integrations are: * Python: 38.0.0 * Go: 41.0.0 * Java: 39.0.0 * Node: 41.0.0 * Ruby: 45.0.0 2. [Confirm](https://dashboard.plaid.com/settings/team/products) that you have access to all required Plaid Check products in the Production environment. If you don't have access to Plaid Check, [request access via the Dashboard](https://dashboard.plaid.com/overview/request-products) . In order to use Plaid Check, your end users must be in the US and you must be on a custom pricing plan. #### Changes to Plaid Link initialization  When using Plaid Check products, you must create a user prior to sending the user through Link and initialize Link with the resulting `user_id`. This allows Plaid to associate multiple Items with a single user. 1. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) prior to creating a Link token: * Include identity info in the `identity` object. At minimum, the following fields must be provided: `name`, `date_of_birth`, `emails`, `phone_numbers`, and `addresses` (with at least one email address, phone number, and address designated as `primary`). If you intend to share the report with a GSE (Government-Sponsored Entity) such as Fannie or Freddie, the full SSN is also required via the `id_numbers` field. For all use cases, providing at least a partial SSN is highly recommended, since it improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. * Store the `user_id` in your database. 2. Update your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request: * Include the `user_id` string from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . * In the `products` array, replace `income_verification` with `cra_base_report` and `cra_income_insights`. * Remove the `income_verification` object. * Add a `cra_options` object and specify `days_requested` (minimum 180). * If you haven't already, set `webhook` to your webhook endpoint listener URL. Unlike Bank Income, Plaid Check requires the use of webhooks. * Provide a `consumer_report_permissible_purpose` * (Optional) To allow linking multiple Items in one session, set `enable_multi_item_link` to `true`. ```node const request: LinkTokenCreateRequest = { loading_sample: true }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```python request = LinkTokenCreateRequest( loading_sample=True ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "loading_sample": true }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { loading_sample: true } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .loadingSample(true); Response response = client .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```go request := plaid.NewLinkTokenCreateRequest( "Sample App App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetLoadingSample(true) linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := linkTokenCreateResp.GetLinkToken(); ``` For more details, see the Plaid Check [Implementation guide](https://plaid.com/docs/check/add-to-app/index.html.md) . ##### Adding Consumer Report to existing Items  To enable an existing Income-enabled Item for Consumer Report, call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) as described above, but include the Item's `access_token` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . When Link is launched, the end user will go through the Consumer Report consent flow, and on successful completion of the flow, the Item will be enabled for Consumer Report. #### Update product API calls and webhook listeners  Unlike Bank Income, Plaid Check uses webhooks with async report generation. 1. Add webhook listener endpoints for [USER\_CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_ready) and [USER\_CHECK\_REPORT\_FAILED](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_failed) . * Upon receiving the [USER\_CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_ready) webhook, call product endpoints such as [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) . * Upon receiving the [USER\_CHECK\_REPORT\_FAILED](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_failed) webhook, call [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) to determine why Items are in a bad state. If appropriate, send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to repair the Item. 2. Replace any Income endpoints and webhook listeners with the equivalent Plaid Check endpoint or webhook listener, using the [API response comparison sheet](https://docs.google.com/spreadsheets/d/1sjzpbPNjz0bF0Ndaly0tShMFgAZ2M9zdvBcQMlDKJbE/edit?gid=727344192#gid=727344192) to map response fields between the old endpoints and new endpoints. | Income endpoint | Equivalent Plaid Check endpoint | | --- | --- | | [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) | None (remove) | | [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) | [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) and/or [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) | | [/credit/bank\_income/pdf/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomepdfget) | [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) with `add_ons: ["cra_income_insights"]` | | Income webhook | Equivalent Plaid Check webhook | | --- | --- | | `BANK_INCOME_REFRESH_COMPLETE` | `USER_CHECK_REPORT_READY` | #### API response comparison  This [Google Sheet](https://docs.google.com/spreadsheets/d/1sjzpbPNjz0bF0Ndaly0tShMFgAZ2M9zdvBcQMlDKJbE/edit?gid=727344192#gid=727344192) highlights the correspondences between Bank Income and Plaid Check Income Insights schemas. If you are using other Plaid Inc. products, note that the `account_id` returned in API responses from endpoints prefixed with `/cra/` will not match the `account_id` returned in responses from non-CRA Plaid endpoints. --- # Consumer Report (by Plaid Check) - Migrate from Transactions | Plaid Docs Migrate from Transactions to Plaid Consumer Report  =================================================== #### Switch to CRA Base Report for FCRA-compliant reporting with enhanced data coverage  This guide will walk you through how to migrate from accessing bank data with Plaid's [Transactions](https://plaid.com/products/transactions/) product to generating Base Reports with Plaid's [Consumer Report](https://plaid.com/check/income-and-underwriting/) product. The CRA Base Report includes account balance, account ownership, and transaction data, and is designed for use cases that require FCRA-compliant consumer reporting, such as tenant screening, income verification, and credit decisioning. #### Why migrate?  While the Transactions product gives you historical transaction data, the CRA Base Report enhances this by: * Supporting FCRA-compliant usage * Bundling additional data (identity, balance, account metadata) in a single report * Managing the explicit consumer consent and disclosures required for underwriting use cases in the US If your use case involves evaluating the financial standing of US-based end users for underwriting, credit, or leasing, you should use the CRA Base Report instead of Transactions. #### Prerequisites  1. To use Consumer Report, it is strongly recommended to update your Plaid client library to the latest version. The minimum required versions for new Consumer Report integrations are: * Python: 38.0.0 * Go: 41.0.0 * Java: 39.0.0 * Node: 41.0.0 * Ruby: 45.0.0 2. [Confirm](https://dashboard.plaid.com/settings/team/products) you have access to Plaid Check products in Production. If not, [request access via the Dashboard](https://dashboard.plaid.com/overview/request-products) . #### Changes to Plaid Link initialization  When using Plaid Check products, you must create a user before initializing Link. This allows Plaid to associate multiple Items with a single user. 1. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) before [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . * Include the `identity` object. At minimum, the following fields must be provided and non-empty: `name`, `date_of_birth`, `emails`, `phone_numbers`, and `addresses` (with at least one email address, phone number, and address designated as `primary`). If you intend to share the report with a GSE (Government-Sponsored Entity) such as Fannie or Freddie, the full SSN is also required via the `id_numbers` field. For all use cases, providing at least a partial SSN is highly recommended, since it improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. * Store the `user_id` in your database. 2. Update your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call: * Remove the `transactions` object (if present) from the call. * Include the `user_id` from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . * Replace `transactions` with `cra_base_report` (and any other CRA products) in the `products` array. * Add a `cra_options` object with `days_requested` (min 180). * Provide a `consumer_report_permissible_purpose`. * (Optional) To allow multi-institution linking, set `enable_multi_item_link` to `true`. ```node const request: LinkTokenCreateRequest = { loading_sample: true }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```python request = LinkTokenCreateRequest( loading_sample=True ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "loading_sample": true }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { loading_sample: true } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .loadingSample(true); Response response = client .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```go request := plaid.NewLinkTokenCreateRequest( "Sample App App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetLoadingSample(true) linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := linkTokenCreateResp.GetLinkToken(); ``` ##### Adding Consumer Report to existing Items  To enable an existing Transactions-enabled Item for Consumer Report, call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) as described above, but include the Item's `access_token` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . When Link is launched, the end user will go through the Consumer Report consent flow, and on successful completion of the flow, the Item will be enabled for Consumer Report. #### Changes to post-Link integration  #### Update product API calls and webhook listeners  1. Update your webhook listener endpoints, adding listeners for Plaid Check. * Upon receiving the [USER\_CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_ready) webhook, call product endpoints such as [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) or (if using) [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) . * Upon receiving the [USER\_CHECK\_REPORT\_FAILED](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_failed) webhook, call [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) to determine why Items are in a bad state. If appropriate, send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to repair the Item. 2. If you're still using other Plaid products like [Auth](https://plaid.com/products/auth/) or [Balance](https://plaid.com/products/balance/) , continue retrieving and exchanging the public token. Otherwise, it's no longer needed. #### Mapping API responses  This [Google Sheet](https://docs.google.com/spreadsheets/d/1toj71Afemtu0rSjgh7AAGgBcZC7U0vYXKCDvKSSWTls/edit?gid=820738585#gid=820738585) highlights the correspondences between Transactions and CRA Base Report schemas. If you are using other Plaid Inc. products, note that the `account_id` returned in API responses from endpoints prefixed with `/cra/` will not match the `account_id` returned in responses from non-CRA Plaid endpoints. #### Migrating existing Items  There is no way to directly migrate an existing Transactions-enabled Item to Plaid Check. Instead, you must delete the old Item using [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) and prompt the user to go through the Link flow again, using a Link token that is enabled for Plaid Check. If you are ready to migrate all Items, use [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) to delete the Transactions-enabled Items, and prompt your users to return to your app to re-add their accounts using the new Plaid Check-enabled flow. You can also perform this process in stages, disabling only a percentage of Items at a time. The most conservative gradual migration strategy is to not delete the Transactions-enabled Item until it is in an unhealthy state that requires user interaction to fix (e.g. `ITEM_LOGIN_REQUIRED`). At that time, instead of sending the Item through update mode, delete the Item using [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) and prompt your users to re-add their accounts using the new Plaid-Check enabled flow. #### Removing Transactions logic for existing Items  Depending on your use case and business, you may want to leave existing Transactions-enabled Items in place and perform a gradual migration, as described above. Do not remove Transactions logic unless you are no longer using any Transactions-enabled Items. 1. Remove handling for Transactions webhooks, including `SYNC_UPDATES_AVAILABLE`, `INITIAL_UPDATE`, `HISTORICAL_UPDATE`, `DEFAULT_UPDATE`, `RECURRING_TRANSACTIONS_UPDATE` 2. Remove calls to `/transactions/` endpoints such as [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) , [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) , or [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) , as well as any handling for transactions-specific logic, such as transactions updates and pagination. 3. Remove handling for the `TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION` error. 4. If you have existing Transactions-enabled Items you will no longer be using, call [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) to delete these Items so you will no longer be billed for Transactions. --- # Consumer Report (by Plaid Check) - Share data with partners | Plaid Docs Sharing Consumer Report data with partners  =========================================== #### Share Consumer Report data with approved partners using OAuth tokens  #### Overview  For eligible product use cases, Plaid Check provides the ability to share Consumer Reporting Agency (CRA) report information with approved partners (Fannie Mae, Freddie Mac, or Experian) using OAuth. To share CRA report information with partners, you need to create an OAuth access token associated with a previously created `user_id` that your partner can use to access the information. #### Creating an OAuth token  To create an access token that will be provided to your partner, call [/oauth/token](https://plaid.com/docs/api/oauth/index.html.md#oauthtoken) following the example below. For the `subject_token`, provide the `user_id` that you created using [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . The `audience` must match the partner you are sharing with. Valid values are: * `urn:plaid:params:cra-partner:experian` * `urn:plaid:params:cra-partner:fannie-mae` * `urn:plaid:params:cra-partner:freddie-mac` You can also provide multiple comma-separated values to create a token that will work with multiple partners. For example: `"audience": "urn:plaid:params:cra-partner:experian,urn:plaid:params:cra-partner:fannie-mae"` /oauth/token/ request ```bash curl 'https://sandbox.plaid.com/oauth/token' \ --header 'Content-Type: application/json' \ --data '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange", "scope": "user:read", "subject_token_type":"urn:plaid:params:credit:multi-user", "audience": "urn:plaid:params:cra-partner:fannie-mae", "subject_token": "usr_9nSp2KuZ2x4JDw" }' ``` /oauth/token response ```bash { "access_token": "pda-RDdg0TUCB0FB25_UPIlnhA==", "expires_in": 2591999, "refresh_token": "Rpdr--viXurkDg88d5zf8m6Wl0g==", "request_id": "vPamXI8hYXPl7P2", "token_type": "Bearer" } ``` You can then provide the `access_token` to your partner. #### Revoking an OAuth token  To revoke your token, call [/oauth/revoke](https://plaid.com/docs/api/oauth/index.html.md#oauthrevoke) , passing in the `access_token` and/or `refresh_token` as the `token` value. /oauth/revoke request ```bash curl -X POST https://sandbox.plaid.com/oauth/revoke \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "token": "pda-RDdg0TUCB0FB25_UPIlnhA==" }' ``` /oauth/revoke response ```bash { "request_id": "pCDVCQK8ve2MzhM" } ``` --- # Consumer Report (by Plaid Check) - Onboard users with Plaid Layer | Plaid Docs Onboard users with Layer  ========================= #### A guide to integrating Layer with Plaid Check  #### Overview  This guide will walk you through how to onboard users to Plaid Check with Layer. This process involves creating a user, onboarding the user with Layer, and retrieving the user's Plaid Check data. #### Integration steps  ##### Create a user  1. Create a `user_id` using the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint. At this stage, the `identity` field is optional. ##### Onboard the user with Layer  1. Onboard the user by following Layer's [Integration Overview steps](https://plaid.com/docs/layer/index.html.md#integration-overview) . When creating the Link token via [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) , pass in the `user_id` you created in the `user.user_id` field and be sure the template used has CRA products enabled. If you are using Transactions in conjunction with both CRA products and Layer, then when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , provide `transactions` in the `additional_consented_products` array (rather than the `products` array) and call [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) only _after_ receiving the `USER_CHECK_REPORT_READY` webhook. This is necessary to avoid a known issue with Chase Bank Items in which CRA reports may fail to generate for Layer sessions if a Transactions extraction is triggered before the CRA report generation is complete. 1. Call [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) to retrieve user-permissioned identity information. 2. After processing the identity information, update the Plaid user record by calling the [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) endpoint. Populate the `identity` field with the relevant information. At minimum, the following fields must be provided and non-empty: `name`, `date_of_birth`, `emails`, `phone_numbers`, and `addresses` (with at least one email address, phone number, and address designated as `primary`). Providing at least a partial SSN via the `id_numbers` field is highly recommended, since it improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests. ##### Retrieve the user's Plaid Check data  1. Now that the identity information has been added to the user record, you can generate a Consumer Report by calling [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) . 2. Once the Consumer Report has been generated (indicated by a `USER_CHECK_REPORT_READY` webhook), retrieve the report by calling [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) , [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) , [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) , or [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) . --- # Enrich - Introduction to Enrich | Plaid Docs Introduction to Enrich   ======================== #### Enrich your transaction data with merchant, category, and location insights.  Get started with Enrich [API Reference](https://plaid.com/docs/api/products/enrich/index.html.md) #### Overview  Enrich (US/CA only) makes it easy to work with transaction data generated by your own banking products or retrieved from other non-Plaid sources. Enrich brings context and meaning to your data by enriching it with detailed merchant, category, and location information. The enriched data can be used to build apps and features that help users manage their cash flow, earn rewards, and discover other financial products to help them reach their financial goals. [Prefer to learn by watching? Get an overview of how Enrich works in just 3 minutes!](https://www.youtube.com/watch?v=2-iJtjzE_6U) #### Sample Enrich data  Below is an example of the enrichments Plaid can provide for a transaction. Sample transaction: ```text PURCHASE WM SUPERCENTER #1700 POWAY CAUS ``` Enrichments returned by Plaid: ```json "counterparties": [{ "name": "Walmart", "type": "merchant", "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "website": "walmart.com", "entity_id": "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM" }], "entity_id" : "O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM", "location": { "address": "13425 Community Rd", "city": "Poway", "region": "CA", "country": "US", "postal_code": "92064", "store_number": "1700", "lat": 32.959068, "lon": -117.037666 }, "logo_url": "https://plaid-merchant-logos.plaid.com/walmart_1100.png", "merchant_name": "Walmart", "payment_channel": "in store", "personal_finance_category": { "detailed": "GENERAL_MERCHANDISE_SUPERSTORES", "primary": "GENERAL_MERCHANDISE" }, "personal_finance_category_icon_url": "https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png", "website": "walmart.com", ``` #### Testing Enrich  Enrich is available for use in all environments. Sandbox: Test the integration with sample transaction data. Send a request with data from this [preset list](https://plaid.com/documents/enrich_sandbox_preset_transactions.csv) of sample transactions to receive a response. Production: Get real enrichments for all your transactions. * If you don't yet have a Plaid plan, or are on a Pay-as-you-go or Growth plan, you can get access to Enrich by submitting a [Production request](https://dashboard.plaid.com/onboarding/) . * Existing Custom plan customers can self-enable for Enrich by agreeing to the terms of service in the [Dashboard](https://dashboard.plaid.com/settings/platform/enrich) . When testing Enrich in Production, make sure to use input data and amounts that are as realistic as possible, as all input fields, not just `description`, are used to analyze transactions. For more details and best practices on testing Enrich, see the [Enrich Testing Guide](https://docs.google.com/document/d/1i4MNohhIYQ5lG-Qn7BC7O5DwO47tcG-Yy1rHoZcVmx8/edit?tab=t.0#heading=h.yiyk3gvjtv90) . #### Enrich integration process  1. Prepare your transaction data for enrichment. Plaid accepts a maximum of 100 transactions per request. For each transaction, include the `description`, `amount`, `direction`, `iso_currency_code` and `id`. For the best results, provide values in the optional `location`, `mcc`, and/or `date_posted` fields, if available. 2. Call [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) to send Plaid your transactions. 3. Plaid will provide an API response with all available enrichments for the transactions. #### Enrich pricing  Enrich is billed on a [flexible fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flexible-fee) ; you will be billed based on the number of transactions sent for enrichment. To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) . --- # Errors - API errors | Plaid Docs API Errors  =========== #### Guide to troubleshooting API errors  #### INTERNAL\_SERVER\_ERROR or plaid-internal-error  ##### Plaid was unable to process the request  ##### Sample user-facing error message  Something went wrong: You can try again later or find another bank to continue ##### Link user experience  Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account. ##### Common causes  * Plaid received an unsupported response from a financial institution, which frequently corresponds to an [institution](https://plaid.com/docs/errors/institution/index.html.md) error. * Plaid is experiencing internal system issues. * A product endpoint request was made for an Item at an OAuth-based institution, but the end user did not authorize the Item for the specific product, or has revoked Plaid's access to the product. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share specific details, such as identity data, or account and routing number information, even if they have already opted in to sharing information about a specific account. ##### Troubleshooting steps  If the error persists, please submit a [Support](https://dashboard.plaid.com/support/new/) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`. API error response ```json http code 500 { "error_type": "API_ERROR", "error_code": "INTERNAL_SERVER_ERROR", "error_message": "an unexpected error occurred", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### PLANNED\_MAINTENANCE  ##### Plaid's systems are undergoing maintenance and API operations are disabled  ##### Sample user-facing error message  Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time ##### Link user experience  Your user will be redirected to the Institution Select pane to retry connecting their Item or a different account. ##### Common causes  * Plaid's systems are under maintenance and API operations are temporarily disabled. Advance notice will be provided when a maintenance window is planned. ##### Troubleshooting steps  If you have not been previously informed of planned maintenance, please reach out to Plaid [Support](https://dashboard.plaid.com/support/new/) for more information. API error response ```json http code 503 { "error_type": "API_ERROR", "error_code": "PLANNED_MAINTENANCE", "error_message": "the Plaid API is temporarily unavailable due to planned maintenance. visit https://status.plaid.com/ for more information", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Assets errors | Plaid Docs Assets Errors  ============== #### Guide to troubleshooting Assets errors  #### PRODUCT\_NOT\_ENABLED  ##### Common causes  * One or more of the Items in the Asset Report was not initialized with the Assets product. Unlike some products, Assets cannot be initialized "on-the-fly" and must be initialized during the initial link process. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "ASSET_REPORT_ERROR", "error_code": "PRODUCT_NOT_ENABLED", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### DATA\_UNAVAILABLE  ##### Common causes  * One or more of the Items in the Asset Report has experienced an error. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "ASSET_REPORT_ERROR", "error_code": "DATA_UNAVAILABLE", "error_message": "unable to pull sufficient data for all items to generate this report. please see the \"causes\" field for more details", "display_message": null, "causes": [ { "display_message": null, "error_code": "ITEM_LOGIN_REQUIRED", "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state", "error_type": "ITEM_ERROR", "item_id": "pZ942ZA0npFEa0BgLCV9DAQv3Zq8ErIZhc81F" } ], "request_id": "HNTDNrA8F1shFEW" } ``` #### PRODUCT\_NOT\_READY  Note that this error should not be confused with the [PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/item/index.html.md#product_not_ready) error of type `ITEM_ERROR`, which has different causes. ##### Common causes  * [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) or [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) was called before the Asset Report generation completed. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "ASSET_REPORT_ERROR", "error_code": "PRODUCT_NOT_READY", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### ASSET\_REPORT\_GENERATION\_FAILED  ##### Common causes  * Plaid is experiencing temporary difficulties generating Asset Reports. * The Asset Report was too large to generate. ##### Troubleshooting steps  If the error persists, please submit a [Support](https://dashboard.plaid.com/support/new/) ticket. API error response ```json http code 400 { "error_type": "ASSET_REPORT_ERROR", "error_code": "ASSET_REPORT_GENERATION_FAILED", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_PARENT  ##### Common causes  * An endpoint that creates a copy or modified copy of an Asset Report (such as [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) or [/asset\_report/audit\_copy/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copycreate) ) was called, but the original Asset Report does not exist, either because it was never successfully created in the first place or because it was deleted. API error response ```json http code 400 { "error_type": "ASSET_REPORT_ERROR", "error_code": "INVALID_PARENT", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INSIGHTS\_NOT\_ENABLED  ##### Common causes  * [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) or [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) was called with `enable_insights` set to `true` by a Plaid developer account that has not been enabled for access to Asset Reports with Insights. API error response ```json http code 400 { "error_type": "ASSET_REPORT_ERROR", "error_code": "INSIGHTS_NOT_ENABLED", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INSIGHTS\_PREVIOUSLY\_NOT\_ENABLED  ##### Common causes  * [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) or [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) was called with `enable_insights` set to `true` by a Plaid developer account that is currently enabled for Asset Reports with Insights, but was not enabled at the time that the report was created. API error response ```json http code 400 { "error_type": "ASSET_REPORT_ERROR", "error_code": "INSIGHTS_PREVIOUSLY_NOT_ENABLED", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### DATA\_QUALITY\_CHECK\_FAILED  ##### Common causes  * The extracted data from the financial institution showed signs of poor data quality, preventing the generation of an accurate report. API error response ```json http code 400 { "error_type": "ASSET_REPORT_ERROR", "error_code": "DATA_QUALITY_CHECK_FAILED", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Check Report errors | Plaid Docs Check Report Errors  ==================== #### Guide to troubleshooting Check Report errors  #### CONSUMER\_REPORT\_EXPIRED  ##### Common causes  * The Check Report has expired as 24 hours have passed since its creation, so it is no longer retrievable. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "CONSUMER_REPORT_ERROR", "error_code": "CONSUMER_REPORT_EXPIRED", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### DATA\_UNAVAILABLE  ##### Common causes  * Plaid Check failed to retrieve data from the user's financial institutions to generate Check Report product data. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "CHECK_REPORT_ERROR", "error_code": "DATA_UNAVAILABLE", "error_message": "The Check Report you are trying to pull does not have sufficient transactions data to generate a report.", "display_message": null, "causes": [ { "display_message": null, "error_code": "ITEM_LOGIN_REQUIRED", "error_message": "The login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state", "error_type": "ITEM_ERROR", "item_id": "pZ942ZA0npFEa0BgLCV9DAQv3Zq8ErIZhc81F" } ], "request_id": "HNTDNrA8F1shFEW" } ``` #### PRODUCT\_NOT\_READY  Note that this error should not be confused with the [PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/item/index.html.md#product_not_ready) error of type `ITEM_ERROR`, which has different causes. ##### Common causes  * `/check_report/.../get` was called before report generation completed. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "CONSUMER_REPORT_ERROR", "error_code": "PRODUCT_NOT_READY", "error_message": "The consumer report you are trying to pull is not ready. Please wait for a CHECK_REPORT_READY webhook to fetch data", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INSTITUTION\_TRANSACTION\_HISTORY\_NOT\_SUPPORTED  ##### Common causes  * The user's financial institution does not support the length of transaction history you require ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "CHECK_REPORT_ERROR", "error_code": "INSTITUTION_TRANSACTION_HISTORY_NOT_SUPPORTED", "error_message": "The user’s bank does not support the transactions range you require. Lowering the days_required may result in success.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INSUFFICIENT\_TRANSACTION\_DATA  ##### Common causes  * The user does not have sufficient transactions data to generate income insights, partner insights, or cashflow insights. The `error_message` will provide more detail on what data is missing. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "CHECK_REPORT_ERROR", "error_code": "INSUFFICIENT_TRANSACTION_DATA", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### NO\_ACCOUNTS  ##### Common causes  * The user does not the correct accounts linked to generate income insights. The `error_message` will provide more detail on what data is missing. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "CHECK_REPORT_ERROR", "error_code": "NO_ACCOUNTS", "error_message": "No depository accounts were found for this user", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### NETWORK\_CONSENT\_REQUIRED  ##### Common causes  * The user did not provide consent in link to share Plaid network data. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "CHECK_REPORT_ERROR", "error_code": "NETWORK_CONSENT_REQUIRED", "error_message": "User has not provided consent to share network data", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### DATA\_QUALITY\_CHECK\_FAILED  ##### Common causes  * The extracted data from the financial institution showed signs of poor data quality, preventing the generation of an accurate report. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "CHECK_REPORT_ERROR", "error_code": "DATA_QUALITY_CHECK_FAILED", "error_message": "Bank provided inconsistent transaction history data that has a high chance of error. The bank will need to resolve issues for product data to be generated.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Income errors | Plaid Docs Income errors  ============== #### Guide to troubleshooting Income errors  #### INCOME\_VERIFICATION\_DOCUMENT\_NOT\_FOUND  ##### The requested income verification document was not found.  ##### Common causes  * The document URL is incorrect (for example, it may contain a typo) or has expired. * The document URL has already been accessed. Document URLs can only be used once. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INCOME_VERIFICATION_ERROR", "error_code": "INCOME_VERIFICATION_DOCUMENT_NOT_FOUND", "error_message": "the requested data was not found. Please check the ID supplied.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INCOME\_VERIFICATION\_FAILED  ##### The income verification you are trying to retrieve could not be completed. please try creating a new income verification  ##### Common causes  * The processing of the verification failed to complete successfully. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INCOME_VERIFICATION_ERROR", "error_code": "INCOME_VERIFICATION_FAILED", "error_message": "the income verification you are trying to retrieve could not be completed. please try creating a new income verification", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INCOME\_VERIFICATION\_NOT\_FOUND  ##### The requested income verification was not found.  ##### Common causes  * The Link flow has not been completed with `income_verification` enabled; either the user has not yet completed the Link flow, or the link token was not initialized with the `income_verification` product. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INCOME_VERIFICATION_ERROR", "error_code": "INCOME_VERIFICATION_NOT_FOUND", "error_message": "the requested data was not found. Please check the ID supplied.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INCOME\_VERIFICATION\_UPLOAD\_ERROR  ##### There was an error uploading income verification documents.  ##### Common causes  * The end user's Internet connection may have been interrupted during the upload attempt. ##### Troubleshooting steps  API error response ```json http code 500 { "error_type": "INCOME_VERIFICATION_ERROR", "error_code": "INCOME_VERIFICATION_UPLOAD_ERROR", "error_message": "there was a problem uploading the document for verification. Please try again or recreate an income verification.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### PRODUCT\_NOT\_ENABLED  ##### The Income product has not been enabled.  ##### Common causes  * The Income product has not been enabled. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INCOME_VERIFICATION_ERROR", "error_code": "PRODUCT_NOT_ENABLED", "error_message": "the 'income_verification' product is not enabled for the following client ID: . please ensure that the 'income_verification' is included in the 'product' array when initializing Link and try again.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### PRODUCT\_NOT\_READY  ##### The Income product has not completed processing.  ##### Common causes  * Parsing of the uploaded pay stubs has not yet completed. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INCOME_VERIFICATION_ERROR", "error_code": "PRODUCT_NOT_READY", "error_message": "the requested product is not yet ready. please provide a webhook or try the request again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### VERIFICATION\_STATUS\_PENDING\_APPROVAL  ##### The user has not yet authorized the sharing of this data  ##### Common causes  * The user has not yet authorized access to the data. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INCOME_VERIFICATION_ERROR", "error_code": "VERIFICATION_STATUS_PENDING_APPROVAL", "error_message": "The user has not yet authorized the sharing of this data", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### EMPLOYMENT\_NOT\_FOUND  ##### The requested employment was not found.  ##### Common causes  * The Link flow has not been completed with `employment` enabled; either the user has not yet completed the Link flow, or the link token was not initialized with the `employment` product. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INCOME_VERIFICATION_ERROR", "error_code": "EMPLOYMENT_NOT_FOUND", "error_message": "the requested employment data was not found. Please check the ID supplied.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Overview | Plaid Docs Errors  ======= #### A comprehensive breakdown of all Plaid error codes  #### Most common errors  The following are the most common errors that may occur in response to an API call even if your implementation is correct. This list of common errors excludes Item errors that occur only during the Link flow (typically due to bad data entry by the end user), such as [INVALID\_CREDENTIALS](https://plaid.com/docs/errors/item/index.html.md#invalid_credentials) , and errors that can occur only due to sending invalid input, such as [INVALID\_FIELD](https://plaid.com/docs/errors/invalid-request/index.html.md#invalid_field) . It is recommended that your integration should, at minimum, handle each of the errors below that are applicable to your product and/or integration mode. In the table below, "institution-based products" refers to any product or integration that connects to a bank or other financial institution (i.e., most Plaid products); it excludes products such as Identity Verification, Monitor, Enrich, and Document Income that do not involve making a connection to a financial institution. | Error | Applies to | Summary | | --- | --- | --- | | [ITEM\_LOGIN\_REQUIRED](https://plaid.com/docs/errors/item/index.html.md#item_login_required) | All institution-based products | Item has expired credentials or consent | | [PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/item/index.html.md#product_not_ready) | Signal, Assets, Income, Check, Auth, [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) | Plaid hasn't finished obtaining the data needed to fulfill your request | | [PRODUCTS\_NOT\_SUPPORTED](https://plaid.com/docs/errors/item/index.html.md#products_not_supported) | All institution-based products | The product endpoint isn't compatible with this Item | | [TRANSACTIONS\_SYNC\_MUTATION\_DURING\_PAGINATION](https://plaid.com/docs/errors/transactions/index.html.md#transactions_sync_mutation_during_pagination) | [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) | An update was received during Transactions pagination | | [NO\_ACCOUNTS](https://plaid.com/docs/errors/item/index.html.md#no_accounts) | All institution-based products | Couldn't find any open accounts | | [NO\_AUTH\_ACCOUNTS](https://plaid.com/docs/errors/item/index.html.md#no_auth_accounts-or-no-depository-accounts) | Auth | Couldn't find any debitable checking, savings, or cash management accounts | | [NO\_LIABILITY\_ACCOUNTS](https://plaid.com/docs/errors/item/index.html.md#no_liability_accounts) | Liabilities | Couldn't find any credit accounts | | [NO\_INVESTMENT\_ACCOUNTS](https://plaid.com/docs/errors/item/index.html.md#no_investment_accounts) | Investments | Couldn't find any investment accounts | | [ACCESS\_NOT\_GRANTED](https://plaid.com/docs/errors/item/index.html.md#access_not_granted) | All institution-based products | The end user didn't grant an OAuth permission required for your request | | [ADDITIONAL\_CONSENT\_REQUIRED](https://plaid.com/docs/errors/invalid-input/index.html.md#additional_consent_required) | Integrations in the US or Canada that [add products to Items after Link](https://plaid.com/docs/link/initializing-products/index.html.md#adding-products-post-link) | The end user didn't grant a data scope required for your request | | [INSTITUTION\_NOT\_RESPONDING](https://plaid.com/docs/errors/institution/index.html.md#institution_not_responding) | All institution-based products | Temporary financial institution connectivity outage | | [INSTITUTION\_DOWN](https://plaid.com/docs/errors/institution/index.html.md#institution_down) | All institution-based products | Temporary financial institution connectivity outage | | [RATE\_LIMIT\_EXCEEDED](https://plaid.com/docs/errors/rate-limit-exceeded/index.html.md) | Applications that batch-process Plaid API calls or have heavy traffic spikes | Too many requests made too quickly, or API usage caps hit | | [INTERNAL\_SERVER\_ERROR](https://plaid.com/docs/errors/api/index.html.md#internal_server_error-or-plaid-internal-error) | All products | Internal error or financial institution error not otherwise specified | #### Errors overview 
Item errors
Occur when an Item may be invalid or not supported on Plaid's platform.
ACCESS_NOT_GRANTED
INSTANT_MATCH_FAILED
INSUFFICIENT_CREDENTIALS
INVALID_CREDENTIALS
INVALID_MFA
INVALID_OTP
INVALID_PHONE_NUMBER
INVALID_SEND_METHOD
INVALID_UPDATED_USERNAME
ITEM_CONCURRENTLY_DELETED
ITEM_LOCKED
ITEM_LOGIN_REQUIRED
ITEM_NOT_FOUND
ITEM_NOT_SUPPORTED
MANUAL_VERIFICATION_REQUIRED
MFA_NOT_SUPPORTED
NO_ACCOUNTS
NO_AUTH_ACCOUNTS or no-depository-accounts
NO_INVESTMENT_ACCOUNTS
NO_INVESTMENT_AUTH_ACCOUNTS
NO_LIABILITY_ACCOUNTS
PASSWORD_RESET_REQUIRED
PRODUCT_NOT_ENABLED
PRODUCT_NOT_READY
PRODUCTS_NOT_SUPPORTED
USER_INPUT_TIMEOUT
USER_SETUP_REQUIRED
Institution errors
Occur when there are errors for the requested financial institution.
INSTITUTION_DOWN
INSTITUTION_NO_LONGER_SUPPORTED
INSTITUTION_NOT_AVAILABLE
INSTITUTION_NOT_ENABLED_IN_ENVIRONMENT
INSTITUTION_NOT_RESPONDING
INSTITUTION_REGISTRATION_REQUIRED
UNAUTHORIZED_INSTITUTION
UNSUPPORTED_RESPONSE
API errors
Occur during planned maintenance and in response to API errors.
INTERNAL_SERVER_ERROR or plaid-internal-error
PLANNED_MAINTENANCE
Assets errors
Occur for errors related to Asset endpoints.
PRODUCT_NOT_ENABLED
DATA_UNAVAILABLE
PRODUCT_NOT_READY
ASSET_REPORT_GENERATION_FAILED
INVALID_PARENT
INSIGHTS_NOT_ENABLED
INSIGHTS_PREVIOUSLY_NOT_ENABLED
DATA_QUALITY_CHECK_FAILED
Payment errors
Occur for errors related to Payment Initiation endpoints.
PAYMENT_BLOCKED
PAYMENT_CANCELLED
PAYMENT_INSUFFICIENT_FUNDS
PAYMENT_INVALID_RECIPIENT
PAYMENT_INVALID_REFERENCE
PAYMENT_INVALID_SCHEDULE
PAYMENT_REJECTED
PAYMENT_SCHEME_NOT_SUPPORTED
PAYMENT_CONSENT_INVALID_CONSTRAINTS
PAYMENT_CONSENT_CANCELLED
Virtual Account errors
Occur for errors related to Virtual Account endpoints.
TRANSACTION_INSUFFICIENT_FUNDS
TRANSACTION_AMOUNT_EXCEEDED
TRANSACTION_ON_SAME_ACCOUNT
TRANSACTION_CURRENCY_MISMATCH
TRANSACTION_IBAN_INVALID
TRANSACTION_BACS_INVALID
TRANSACTION_FAST_PAY_DISABLED
TRANSACTION_EXECUTION_FAILED
NONIDENTICAL_REQUEST
REQUEST_CONFLICT
Transactions errors
Occur for errors related to Transactions endpoints.
TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION
Transfer errors
Occur for errors related to Transfer endpoints.
TRANSFER_NETWORK_LIMIT_EXCEEDED
TRANSFER_ACCOUNT_BLOCKED
TRANSFER_NOT_CANCELLABLE
TRANSFER_UNSUPPORTED_ACCOUNT_TYPE
TRANSFER_FORBIDDEN_ACH_CLASS
TRANSFER_UI_UNAUTHORIZED
TRANSFER_ORIGINATOR_NOT_FOUND
INCOMPLETE_CUSTOMER_ONBOARDING
UNAUTHORIZED_ACCESS
Signal errors
Occur for errors related to Signal endpoints.
ADDENDUM_NOT_SIGNED
CLIENT_TRANSACTION_ID_ALREADY_IN_USE
INVALID_CONFIGURATION_STATE
NOT_ENABLED_FOR_SIGNAL_TRANSACTION_SCORE_RULESETS
RULESET_NOT_FOUND
SIGNAL_TRANSACTION_NOT_INITIATED
Income errors
Occur for errors related to Income endpoints.
INCOME_VERIFICATION_DOCUMENT_NOT_FOUND
INCOME_VERIFICATION_FAILED
INCOME_VERIFICATION_NOT_FOUND
INCOME_VERIFICATION_UPLOAD_ERROR
PRODUCT_NOT_ENABLED
PRODUCT_NOT_READY
VERIFICATION_STATUS_PENDING_APPROVAL
EMPLOYMENT_NOT_FOUND
Sandbox errors
Occur when invalid parameters are supplied in the Sandbox environment.
SANDBOX_PRODUCT_NOT_ENABLED
SANDBOX_WEBHOOK_INVALID
SANDBOX_TRANSFER_EVENT_TRANSITION_INVALID
Invalid Request errors
Occur when a request is malformed and cannot be processed.
MISSING_FIELDS
UNKNOWN_FIELDS
INVALID_FIELD
INVALID_CONFIGURATION
INCOMPATIBLE_API_VERSION
INVALID_BODY
INVALID_HEADERS
NOT_FOUND
NO_LONGER_AVAILABLE
SANDBOX_ONLY
INVALID_ACCOUNT_NUMBER
Invalid Input errors
Occur when all fields are provided, but the values provided are incorrect in some way.
ADDITIONAL_CONSENT_REQUIRED
DIRECT_INTEGRATION_NOT_ENABLED
INCORRECT_DEPOSIT_VERIFICATION
INVALID_ACCESS_TOKEN
INVALID_ACCOUNT_ID
INVALID_API_KEYS
INVALID_AUDIT_COPY_TOKEN
INVALID_INSTITUTION
INVALID_LINK_CUSTOMIZATION
INVALID_PROCESSOR_TOKEN
INVALID_PRODUCT
INVALID_PUBLIC_TOKEN
INVALID_LINK_TOKEN
INVALID_STRIPE_ACCOUNT
INVALID_USER_ID
INVALID_USER_IDENTITY_DATA
INVALID_USER_TOKEN
INVALID_WEBHOOK_VERIFICATION_KEY_ID
PROFILE_ACCESS_FORBIDDEN
PROFILE_AUTHENTICATION_FAILED
UNAUTHORIZED_ENVIRONMENT
UNAUTHORIZED_ROUTE_ACCESS
USER_PERMISSION_REVOKED
TOO_MANY_VERIFICATION_ATTEMPTS
Invalid Result errors
Occur when a request is valid, but the output would be unusable for any supported flow.
PLAID_DIRECT_ITEM_IMPORT_RETURNED_INVALID_MFA
Rate Limit Exceeded errors
Occur when an excessive number of requests are made in a short period of time.
ACCOUNTS_LIMIT
ACCOUNTS_BALANCE_GET_LIMIT
AUTH_LIMIT
BALANCE_LIMIT
CREDITS_EXHAUSTED
IDENTITY_LIMIT
INSTITUTIONS_GET_LIMIT
INSTITUTIONS_GET_BY_ID_LIMIT
INSTITUTION_RATE_LIMIT
INVESTMENT_HOLDINGS_GET_LIMIT
INVESTMENT_TRANSACTIONS_LIMIT
ITEM_GET_LIMIT
RATE_LIMIT
TRANSACTIONS_LIMIT
TRANSACTIONS_REFRESH_LIMIT
TRANSACTIONS_SYNC_LIMIT
TRIAL_CONNECTION_LIMIT
ReCAPTCHA errors
Occur when a ReCAPTCHA challenge has been presented or failed during the link process.
RECAPTCHA_REQUIRED
RECAPTCHA_BAD
OAuth errors
Occur when there is an error in OAuth authentication.
INCORRECT_OAUTH_NONCE
INCORRECT_LINK_TOKEN
OAUTH_STATE_ID_ALREADY_PROCESSED
OAUTH_STATE_ID_NOT_FOUND
Micro-deposits errors
Occur when there is an error with micro-deposits.
BANK_TRANSFER_ACCOUNT_BLOCKED
Partner errors
Occur when there is an error with creating or managing end customers.
CUSTOMER_NOT_FOUND
FLOWDOWN_NOT_COMPLETE
QUESTIONNAIRE_NOT_COMPLETE
CUSTOMER_NOT_READY_FOR_ENABLEMENT
CUSTOMER_ALREADY_ENABLED
CUSTOMER_ALREADY_CREATED
LOGO_REQUIRED
INVALID_LOGO
CONTACT_REQUIRED
ASSETS_UNDER_MANAGEMENT_REQUIRED
CUSTOMER_REMOVAL_NOT_ALLOWED
OAUTH_REGISTRATION_ERROR
Check Report errors
Occur when there is an error with creating or retrieving a Check Report.
CONSUMER_REPORT_EXPIRED
DATA_UNAVAILABLE
PRODUCT_NOT_READY
INSTITUTION_TRANSACTION_HISTORY_NOT_SUPPORTED
INSUFFICIENT_TRANSACTION_DATA
NO_ACCOUNTS
NETWORK_CONSENT_REQUIRED
DATA_QUALITY_CHECK_FAILED
User errors
Occur when there is an error with creating or managing a user
USER_NOT_FOUND
#### Error schema  Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. **Properties** string A broad categorization of the error. Safe for programmatic use. Possible values: `INVALID_REQUEST`, `INVALID_RESULT`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, `ASSET_REPORT_ERROR`, `RECAPTCHA_ERROR`, `OAUTH_ERROR`, `PAYMENT_ERROR`, `BANK_TRANSFER_ERROR`, `INCOME_VERIFICATION_ERROR`, `MICRODEPOSITS_ERROR`, `SANDBOX_ERROR`, `PARTNER_ERROR`, `SIGNAL_ERROR`, `TRANSACTIONS_ERROR`, `TRANSACTION_ERROR`, `TRANSFER_ERROR`, `CHECK_REPORT_ERROR`, `CONSUMER_REPORT_ERROR`, `USER_ERROR` string The particular error code. Safe for programmatic use. string The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user’s OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user’s OAuth connection to this institution is invalid because the user revoked their connection. string A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. string A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. array In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. integer The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. string The URL of a Plaid documentation page with more information about the error string Suggested steps for resolving the error \[string\] A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. \[string\] A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. --- # Errors - Institution errors | Plaid Docs Institution Errors  =================== #### Guide to troubleshooting Institution errors  #### INSTITUTION\_DOWN  ##### The financial institution is down, either for maintenance or due to an infrastructure issue with their systems.  ##### Sample user-facing error message  Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time ##### Link user experience  Your user will be redirected to the `Institution Select` pane to retry connecting their Item or a different account. ##### Common causes  * The institution is undergoing scheduled maintenance. * The institution is experiencing temporary technical problems. ##### Troubleshooting steps  If the error persists, please submit a 'Persistent HTTP 500 errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/persistent-500) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`. API error responseLink error preview API error response ```json http code 400 { "error_type": "INSTITUTION_ERROR", "error_code": "INSTITUTION_DOWN", "error_message": "this institution is not currently responding to this request. please try again soon", "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.", "request_id": "HNTDNrA8F1shFEW" } ``` #### INSTITUTION\_NOT\_ENABLED\_IN\_ENVIRONMENT  ##### Institution not enabled in this environment  ##### Common causes  You're referencing an institution that exists, but is not enabled for this environment (e.g. calling a Sandbox endpoint with the ID of an institution that is not enabled there). API error response ```json http code 400 { "error_type": "INSTITUTION_ERROR", "error_code": "INSTITUTION_NOT_ENABLED_IN_ENVIRONMENT", "error_message": "Institution not enabled in this environment", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INSTITUTION\_NOT\_RESPONDING  ##### The financial institution is failing to respond to some of our requests. Your user may be successful if they retry another time.  ##### Sample user-facing error message  Couldn't connect to your institution: If you need to use this app immediately, we recommend trying another institution. Errors like this may take some time to resolve, so you may want to try the same account again later. ##### Link user experience  Your user will be redirected to the `Institution Select` pane to retry connecting their Item or a different account. ##### Common causes  * The institution is experiencing temporary technical problems. ##### Troubleshooting steps  If the error persists, please submit a 'Persistent HTTP 500 errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/persistent-500) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`. API error responseLink error preview API error response ```json http code 400 { "error_type": "INSTITUTION_ERROR", "error_code": "INSTITUTION_NOT_RESPONDING", "error_message": "this institution is not currently responding to this request. please try again soon", "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.", "request_id": "HNTDNrA8F1shFEW" } ``` #### INSTITUTION\_NOT\_AVAILABLE  ##### The financial institution is not available this time.  ##### Link user experience  Your user will be redirected to the `Institution Select` pane to retry connecting their Item or a different account. ##### Common causes  * Plaid's connection to an institution is temporarily down for maintenance or other planned circumstances. ##### Troubleshooting steps  If the error persists, please submit a 'Persistent HTTP 500 errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/persistent-500) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`. API error response ```json http code 400 { "error_type": "INSTITUTION_ERROR", "error_code": "INSTITUTION_NOT_AVAILABLE", "error_message": "this institution is not currently responding to this request. please try again soon", "display_message": "This financial institution is not currently responding to requests. We apologize for the inconvenience.", "request_id": "HNTDNrA8F1shFEW" } ``` #### INSTITUTION\_NO\_LONGER\_SUPPORTED  ##### Plaid no longer supports this financial institution.  ##### Sample user-facing error message  Institution Not Supported: Plaid does not support this institution yet, but we are working hard to add coverage based on your interest! In the meantime, please try another institution. ##### Common causes  * The financial institution is no longer supported on Plaid's platform. * The institution has switched from supporting non-OAuth-based connections to requiring OAuth-based connections. API error responseLink error preview API error response ```json http code 400 { "error_type": "INSTITUTION_ERROR", "error_code": "INSTITUTION_NO_LONGER_SUPPORTED", "error_message": "this institution is no longer supported", "display_message": "This financial institution is no longer supported. We apologize for the inconvenience.", "request_id": "HNTDNrA8F1shFEW" } ``` #### UNAUTHORIZED\_INSTITUTION  ##### You are not authorized to create Items for this institution at this time.  ##### Common causes  * Access to this institution is subject to additional verification and must be manually enabled for your account. * You have not yet completed the OAuth registration requirements for the institution. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INSTITUTION_ERROR", "error_code": "UNAUTHORIZED_INSTITUTION", "error_message": "not authorized to create items for this institution", "display_message": "You are not authorized to create items for this institution at this time.", "request_id": "HNTDNrA8F1shFEW" } ``` #### INSTITUTION\_REGISTRATION\_REQUIRED  ##### Your application is not yet registered with the institution.  ##### Common causes  * If your account was recently enabled for full Production access or a Trial plan, it may take up to 1-2 days to get access to certain institutions. * Details about your application must be registered with this institution before use. * You have not completed the Security Questionnaire. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INSTITUTION_ERROR", "error_code": "INSTITUTION_REGISTRATION_REQUIRED", "error_message": "not yet registered to create items for this institution", "display_message": "You must register your application with this institution before you can create items for it.", "request_id": "HNTDNrA8F1shFEW" } ``` #### UNSUPPORTED\_RESPONSE  ##### The data returned from the financial institution is not valid.  ##### Common causes  * The data returned from the financial institution is not supported or is invalid. API error response ```json http code 400 { "error_type": "INSTITUTION_ERROR", "error_code": "UNSUPPORTED_RESPONSE", "error_message": "the data returned from the financial institution is not valid", "display_message": "The data returned from the financial institution is not valid.", "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Invalid Input errors | Plaid Docs Invalid Input Errors  ===================== #### Guide to troubleshooting invalid input errors  #### DIRECT\_INTEGRATION\_NOT\_ENABLED  ##### An attempt was made to create an Item without using Link.  ##### Common causes  * `/item/create` was called directly, without using Link. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "DIRECT_INTEGRATION_NOT_ENABLED", "error_message": "your client ID is only authorized to use Plaid Link. head to the docs (https://plaid.com/docs) to get started.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INCORRECT\_DEPOSIT\_VERIFICATION  ##### The user submitted an incorrect Manual Same-Day micro-deposit verification input during Item verification in Link.  ##### Sample user-facing error message  2 attempts remaining: The code you entered is incorrect. Check your bank statement to find the code in front of ACCTVERIFY. ##### Common causes  * Your user submitted an incorrect micro-deposit verification input when verifying an account via Manual Same-Day micro-deposits. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INCORRECT_DEPOSIT_VERIFICATION", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_ACCESS\_TOKEN  ##### Common causes  * Access tokens are in the format: `access--` * This error can happen when the `access_token` you provided is invalid or pertains to a different API environment ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_ACCESS_TOKEN", "error_message": "could not find matching access token", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_ACCOUNT\_ID  ##### The supplied account\_id is not valid  ##### Common causes  One of the `account_id`(s) specified in the API call's `account_ids` object is invalid or does not exist. * Your integration is passing a correctly formatted, but invalid `account_id` for the Item in question. * The underlying account may have been closed at the bank, and thus removed from our API. * The Item affected is at an institution that uses OAuth-based connections, and the user revoked access to the specific account. * The `account_id` was removed from our API, either completely or a new `account_id` was assigned to the same underlying account. * You are requesting an account that your user has de-selected in the Account Select v2 update flow. ##### Troubleshooting steps  Ensure that your integration only uses `account_id`(s) that belong to the Item in question. Early on in your development it is important to verify that your integration only uses `account_id`(s), and other Plaid identifiers like `item_id`, for the Item that they belong to. Also be sure to preserve the case of any non-numeric characters in Plaid identifiers, as they are case sensitive. ##### Account churn  If the underlying account has not been closed or changed at the bank and the `account_id` no longer appears, Plaid may have removed the account entirely or assigned the account a new `account_id`, a situation known as "account churn". Some common causes for account churn are: * The Item was in an unhealthy state for an extended period of time. If an Item has remained in an error state for over a year, its underlying data may be removed. If the Item is then later refreshed, the Item data will be re-generated, resulting in new `account_id` data. * The bank or user drastically changing the name of the account, e.g. an account named "Savings account" becomes "Jane's vacation fund". * The account's mask is changed by the bank, which can occur when banks change their backend systems. Account churn caused by the latter two reasons is unexpected API behavior. If you experience account churn on an Item that was otherwise healthy, [file a support ticket](https://dashboard.plaid.com/support/new/financial-institutions/missing-data/missing-accounts) . API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_ACCOUNT_ID", "error_message": "failed to find requested account ID for requested item", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_API\_KEYS  ##### The client ID and secret included in the request body were invalid. Find your API keys in the Dashboard.  ##### Common causes  * The API keys are not valid for the environment being used, which can commonly happen when switching between development environments and forgetting to switch API keys ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_API_KEYS", "error_message": "invalid client_id or secret provided", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_AUDIT\_COPY\_TOKEN  ##### The audit copy token supplied to the server was invalid.  ##### Common causes  * You attempted to access an Asset Report using an `audit_copy_token` that is invalid or was revoked using [/asset\_report/audit\_copy/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copyremove) or [/asset\_report/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportremove) . ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_AUDIT_COPY_TOKEN", "error_message": null, "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_INSTITUTION  ##### The institution\_id specified is invalid or does not exist.  ##### Common causes  * The `institution_id` specified is invalid or does not exist. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_INSTITUTION", "error_message": "invalid institution_id provided", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_LINK\_CUSTOMIZATION  ##### The Link customization is not valid for the request.  ##### Common causes  * The Link customization is missing a use case and the session is enabled for Data Transparency Messaging. * This error can happen when requesting to update account selections with a Link customization that does not enable [Account Select v2](https://plaid.com/docs/link/customization/index.html.md#account-select) . ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_LINK_CUSTOMIZATION", "error_message": "requested link customization is not set to update account selection", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_LINK\_TOKEN  ##### The link\_token provided to initialize Link was invalid.  ##### Sample user-facing error message  The credentials you provided were incorrect: For security reasons, your account may be locked after several unsuccessful attempts ##### Common causes  * The `link_token` has expired. A `link_token` lasts at least 30 minutes before expiring. * The `link_token` was already used. A `link_token` can only be used once, except when working in the Sandbox test environment. * The `link_token` was created in a different environment than the one it was used with. For example, a Sandbox `link_token` was used in Production. * A user entered invalid credentials too many times during the Link flow, invalidating the `link_token`. ##### Troubleshooting steps  For more detailed instructions on handling this error, see [Handling invalid Link Tokens](https://plaid.com/docs/link/handle-invalid-link-token/index.html.md) . API error responseLink error preview API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_LINK_TOKEN", "error_message": "invalid link_token provided", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_PROCESSOR\_TOKEN  ##### The processor\_token provided to initialize Link was invalid.  ##### Common causes  * The `processor_token` used to initialize Link was invalid. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_PROCESSOR_TOKEN", "error_message": null, "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_PRODUCT  ##### The product is not a valid configuration value, or your client ID does not have access to this product.  ##### Common causes  * The [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call specified a product name that does not exist. * The [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call specified a product that should be omitted from the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call, such as `balance` or `monitor`. * The endpoint you are trying to access is not enabled for your account in the environment where you are trying to use it. For example, Identity Verification access is only available in Sandbox after you have received Production access. * Your integration is using a partner endpoint integration that has not yet been enabled in the Dashboard. * Your integration is attempting to call a processor endpoint on an Item that was initialized with products that are not compatible with processor endpoints. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_PRODUCT", "error_message": "client is not authorized to access the following products: [\"identity_verification\"]", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_USER\_ID  ##### The user id is not in a valid format  ##### Common causes  * A different identifier (such as a `client_user_id` or `user_token`) was sent instead of a `user_id`. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_USER_ID", "error_message": "user.user_id must be a non-empty string", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_USER\_IDENTITY\_DATA  ##### The user identity provided failed Plaid's validation checks. The error message will contain specific details about which field(s) failed validation.  ##### Common causes  * Invalid phone number. Plaid phone number validation checks not only for the correct number of digits, but also for a valid area code, prefix, etc., even in the Sandbox environment. * Required identity fields are empty or contain only whitespace * Invalid email address format * Invalid date of birth format (must be YYYY-MM-DD) * Incomplete address data (missing required fields when any address field is provided) ##### Troubleshooting steps  API error response ```json http code 403 { "error_type": "USER_ERROR", "error_code": "INVALID_USER_IDENTITY_DATA", "error_message": "Invalid email format.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### ADDITIONAL\_CONSENT\_REQUIRED  ##### The end user has not provided consent to the requested product  ##### Common causes  * You are using a Link flow that is enabled for [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) and are trying to access an endpoint you did not collect consent for. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "ADDITIONAL_CONSENT_REQUIRED", "error_message": "client does not have user consent to access the PRODUCT_AUTH product", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_PUBLIC\_TOKEN  ##### Common causes  * Public tokens are in the format: `public--` * This error can happen when the `public_token` you provided is invalid, pertains to a different API environment, or has expired. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_PUBLIC_TOKEN", "error_message": "could not find matching public token", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_STRIPE\_ACCOUNT  ##### The supplied Stripe account is invalid  ##### Common causes  After [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) was called, Plaid received a response from Stripe indicating that the Stripe account specified in the API call's `account_id` is invalid. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_STRIPE_ACCOUNT", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_USER\_TOKEN  ##### The supplied user token is invalid  ##### Common causes  * The user token is not associated with the given user ID. * The user token is invalid or pertains to a different API environment. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_USER_TOKEN", "error_message": "could not find matching user token", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_WEBHOOK\_VERIFICATION\_KEY\_ID  ##### The key\_id provided to the webhook verification endpoint was invalid.  ##### Common causes  * A request was made to [/webhook\_verification\_key/get](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md#get-webhook-verification-key) using an invalid `key_id`. * The call to [/webhook\_verification\_key/get](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md#get-webhook-verification-key) was made from an environment different than the one the webhook was sent from (for example, verification of a Sandbox webhook was attempted against Production). ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "INVALID_WEBHOOK_VERIFICATION_KEY_ID", "error_message": "invalid key_id provided. note that key_ids are specific to Plaid environments, and verification requests must be made to the same environment that the webhook was sent from", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### PROFILE\_ACCESS\_FORBIDDEN  ##### The end user authenticated their device, but Plaid could not use the saved information associated with their profile  ##### Common causes  * The end user was able to authenticate their device by completing SNA or SMS OTP, but authentication of their Plaid account failed for other reasons, such as phone ownership changes. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "PROFILE_ACCESS_FORBIDDEN", "error_message": "access to this profile is forbidden", "display_message": "For security reasons, we couldn’t use the information saved to this Plaid account.", "request_id": "HNTDNrA8F1shFEW" } ``` #### PROFILE\_AUTHENTICATION\_FAILED  ##### The end user could not authenticate the device associated with their profile  ##### Common causes  * When prompted to verify their phone number by entering a code delivered to their number via SMS, the end user entered three incorrect codes. (The first and second incorrect codes will result in an `INVALID_OTP` error, which is recoverable within Link and will not prompt the user to end the Link session.) ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "PROFILE_AUTHENTICATION_FAILED", "error_message": "the profile could not be authenticated", "display_message": "We were not able to authenticate your access to this Plaid account.", "request_id": "HNTDNrA8F1shFEW" } ``` #### TOO\_MANY\_VERIFICATION\_ATTEMPTS  ##### The user attempted to verify their Manual Same-Day micro-deposit codes more than 3 times and their Item is now permanently locked. The user must retry submitting their account information in Link.  ##### Sample user-facing error message  No attempts remaining: The code you entered is incorrect. You have no more attempts left. ##### Common causes  * Your user repeatedly submitted incorrect micro-deposit codes when verifying an account via Manual Same-Day micro-deposits. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "TOO_MANY_VERIFICATION_ATTEMPTS", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### UNAUTHORIZED\_ENVIRONMENT  ##### Your client ID does not have access to this API environment. See which environments you are enabled for from the Dashboard.  ##### Sample user-facing error message  Unauthorized Environment: Your Client ID is not authorized to access this API environment. Contact Support to gain access ##### Common causes  * You may not be enabled for the environment you are using. * Your code may be calling a deprecated endpoint. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "UNAUTHORIZED_ENVIRONMENT", "error_message": "you are not authorized to create items in this api environment. Go to the Dashboard (https://dashboard.plaid.com) to see which environments you are authorized for.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### UNAUTHORIZED\_ROUTE\_ACCESS  ##### Your client ID does not have access to this route.  ##### Common causes  * The endpoint you are trying to access must be manually enabled for your account. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "UNAUTHORIZED_ROUTE_ACCESS", "error_message": "you are not authorized to access this route in this api environment.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### USER\_PERMISSION\_REVOKED  ##### The end user has revoked access to their data.  ##### Common causes  * The end user revoked access to their data via the Plaid consumer portal at my.plaid.com. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_INPUT", "error_code": "USER_PERMISSION_REVOKED", "error_message": "the holder of this account has revoked their permission for your application to access it", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Invalid Request errors | Plaid Docs Invalid Request Errors  ======================= #### Guide to troubleshooting invalid request errors  #### INCOMPATIBLE\_API\_VERSION  ##### The request uses fields that are not compatible with the API version being used.  ##### Common causes  * The API endpoint was called using a `public_key` for authentication rather than a `client_id` and `secret`. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_REQUEST", "error_code": "INCOMPATIBLE_API_VERSION", "error_message": "The public_key cannot be used for this endpoint as of version {version-date} of the API. Please use the client_id and secret instead.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_ACCOUNT\_NUMBER  ##### The provided account number was invalid.  ##### Sample user-facing error message  Account or routing number incorrect: Check with your bank and make sure that your account and routing numbers are entered correctly ##### Alternative user-facing error message  _This account does not support ACH debit. Please retry with a different account._ ##### Common causes  * While in the Instant Match, Automated Micro-deposit, or Same-Day Micro-deposit Link flows, the user provided an account number whose last four digits did not match the account mask of their bank account. * If the user entered the correct account number, Plaid may have been unable to retrieve an account mask. * If the user entered the correct account number, the account may be a non-debitable account or a non-supported account type. Common examples of non-debitable depository accounts include savings accounts at Chime or at Navy Federal Credit Union (NFCU). ##### Troubleshooting steps  If the account number was correct and the account was a debitable supported type, please [contact Plaid support](https://dashboard.plaid.com/support/new/) . API error responseLink error preview API error response ```json http code 400 { "error_type": "INVALID_REQUEST", "error_code": "INVALID_ACCOUNT_NUMBER", "error_message": "The provided account number was invalid.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_BODY  ##### The request body was invalid.  ##### Common causes  * The JSON request body was malformed. * The request `content-type` was not of type `application/json`. The Plaid API only accepts JSON text as the MIME media type, with `UTF-8` encoding, conforming to [RFC 4627](http://www.ietf.org/rfc/rfc4627.txt) . API request content-type ```json content-type: "application/json" ``` ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_REQUEST", "error_code": "INVALID_BODY", "error_message": "body could not be parsed as JSON", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_CONFIGURATION  ##### /link/token/create was called with invalid configuration settings  ##### Common causes  * One or more of the configuration objects provided to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) does not match the request schema for that endpoint. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_REQUEST", "error_code": "INVALID_CONFIGURATION", "error_message": "please ensure that the request body is formatted correctly", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_FIELD  ##### One or more of the request body fields were improperly formatted or invalid.  ##### Common causes  * One or more fields in the request body were invalid, malformed, or used a wrong type. The `error_message` field will specify the erroneous field and how to resolve the error. * Personally identifiable information (PII), such as an email address or phone number, was provided for a field where PII is not allowed, such as `user.client_user_id`. * An unsupported country code was used in Production. Consult the [API Reference](https://plaid.com/docs/api/index.html.md) for the endpoint being used for a list of valid country codes. * An request parameter that is optional in the API schema was not provided in a context where it is required. For example, [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) was called without specifying `options.min_last_updated_datetime` on a Capital One (`ins_128026`) Item with non-depository accounts. * The value used in the field is not valid for business logic reasons. For example, [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) or [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) endpoints were called with a `client_transaction_id` for which [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) was never called, or [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) was called using an `authorization_id` whose `decision` value is `declined`. * A request to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) was sent specifying an OAuth redirect URI that was not added to the [allowed redirect URIs](https://dashboard.plaid.com/developers/api) list in the Dashboard. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_REQUEST", "error_code": "INVALID_FIELD", "error_message": "{{ error message is specific to the given / missing request field }}", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_HEADERS  ##### The request was missing a required header.  ##### Common causes  * The request was missing a `header`, typically the `Content-Type` header. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_REQUEST", "error_code": "INVALID_HEADERS", "error_message": "{{ error message is specific to the given / missing header }}", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### MISSING\_FIELDS  ##### The request was missing one or more required fields.  ##### Common causes  * The request body is missing one or more required fields. The `error_message` field will list the missing field(s). ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_REQUEST", "error_code": "MISSING_FIELDS", "error_message": "the following required fields are missing: {fields}", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### NO\_LONGER\_AVAILABLE  ##### The endpoint requested is not available in the API version being used.  ##### Common causes  * The endpoint you requested has been discontinued and no longer exists in the Plaid API. ##### Troubleshooting steps  API error response ```json http code 404 { "error_type": "INVALID_REQUEST", "error_code": "NO_LONGER_AVAILABLE", "error_message": "This endpoint has been discontinued as of version {version-date} of the API.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### NOT\_FOUND  ##### The endpoint requested does not exist.  ##### Common causes  * The endpoint you requested does not exist in the Plaid API. ##### Troubleshooting steps  API error response ```json http code 404 { "error_type": "INVALID_REQUEST", "error_code": "NOT_FOUND", "error_message": "not found", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### SANDBOX\_ONLY  ##### The requested endpoint is only available in Sandbox.  ##### Common causes  * The requested endpoint is only available in the [Sandbox API Environment](https://plaid.com/docs/sandbox/index.html.md) . ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_REQUEST", "error_code": "SANDBOX_ONLY", "error_message": "access to {api/route} is only available in the sandbox environment at https://sandbox.plaid.com/", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### UNKNOWN\_FIELDS  ##### The request included a field that is not recognized by the endpoint.  ##### Common causes  * The request body included one or more extraneous fields. The `error_message` field will list the unrecognized field(s). ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_REQUEST", "error_code": "UNKNOWN_FIELDS", "error_message": "the following fields are not recognized by this endpoint: {fields}", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Invalid Result errors | Plaid Docs Invalid Result errors  ====================== #### Guide to troubleshooting invalid result errors  #### LAST\_UPDATED\_DATETIME\_OUT\_OF\_RANGE  ##### No data is available from the Item within the specified date-time.  ##### Common causes  * [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) was called with a parameter specifying the minimum acceptable data freshness, but no balance data meeting those requirements was available from the institution. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_RESULT", "error_code": "LAST_UPDATED_DATETIME_OUT_OF_RANGE", "error_message": "requested datetime out of range, most recently updated balance 2021-01-01T00:00:00Z", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### PLAID\_DIRECT\_ITEM\_IMPORT\_RETURNED\_INVALID\_MFA  ##### The Plaid Direct Item import resulted in invalid MFA.  ##### Common causes  * No known causes. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "INVALID_RESULT", "error_code": "PLAID_DIRECT_ITEM_IMPORT_RETURNED_INVALID_MFA", "error_message": "Plaid Direct Item Imports should not result in MFA.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Item errors | Plaid Docs Item Errors  ============ #### Guide to troubleshooting Item errors  #### ACCESS\_NOT\_GRANTED  ##### The user did not grant necessary permissions for their account.  ##### Sample user-facing error message  Insufficient Sharing Permissions: There was an error connecting to your account. Try linking your account again by selecting the required information to share with this application. ##### Common causes  * This Item's access is affected by institution-hosted access controls. * The user did not agree to share, or has revoked, access to the data required for the requested product. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share specific details, such as identity data, or account and routing number information, even if they have already opted in to sharing information about a specific account. * The user does not have permission to share required information about the account. This can happen at some institutions using OAuth connections if the user is not the account owner (for example, they have a role such as trustee, investment advisor, power of attorney holder, or authorized cardholder). ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "ACCESS_NOT_GRANTED", "error_message": "access to this product was not granted for the account", "display_message": "The user did not grant the necessary permissions for this product on their account.", "request_id": "HNTDNrA8F1shFEW" } ``` #### INSTANT\_MATCH\_FAILED  ##### Instant Match could not be initialized for the Item.  ##### Common causes  * Instant Auth could not be used for the Item, and Instant Match has been enabled for your account, but a country other than `US` is specified in Link's country code initialization. * The Item does not support Instant Auth or Instant Match. If this is the case, Plaid will automatically attempt to enter a micro-deposit based verification flow. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "INSTANT_MATCH_FAILED", "error_message": "Item cannot be verified through Instant Match. Ensure you are correctly enabling all auth features in Link.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INSUFFICIENT\_CREDENTIALS  ##### The user did not provide sufficient authorization in order to link their account via an OAuth login flow.  ##### Sample user-facing error message  Couldn't connect to Platypus Bank: Please try to sign in again, or connect another institution. ##### Common causes  * Your user abandoned the bank OAuth flow without completing it. ##### Troubleshooting steps  If this error persists, please submit a [Support](https://dashboard.plaid.com/support/new) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`. API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "INSUFFICIENT_CREDENTIALS", "error_message": "insufficient authorization was provided to complete the request", "display_message": "INSUFFICIENT_CREDENTIALS", "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_CREDENTIALS  ##### The financial institution indicated that the credentials provided were invalid.  ##### Sample user-facing error message  The credentials you provided were incorrect: Check that your credentials are the same that you use for this institution ##### Link user experience  Your user will be redirected to the `Credentials` pane to retry entering correct credentials. ##### Common causes  * The user entered incorrect credentials at their selected institution. * Extra spaces, capitalization, and punctuation errors are common causes of `INVALID_CREDENTIALS`. * The institution requires special configuration steps before the user can link their account with Plaid. KeyBank, Interactive Brokers, Morgan Stanley, and Betterment are examples of institutions that require this setup. * The user selected the wrong institution. * Plaid supports institutions that have multiple login portals for the various products they offer, and it is common for users to confuse a different selection for the one which their credentials would actually be accepted. * This confusion is particularly common between Vanguard (brokerage accounts) and My Vanguard Plan (retirement accounts). This is also common for users attempting to link prepaid stored-value cards, as many institutions have separate login portals specifically for those cards. ##### Troubleshooting steps  Note: The Institution may lock a user out of their account after 3-5 repeated attempts, resulting in an [ITEM\_LOCKED](https://plaid.com/docs/errors/item/index.html.md#item_locked) error. If the credentials are confirmed to be legitimate, and a user still cannot authenticate, please submit an 'Invalid credentials errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/invalid-creds) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`. API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "INVALID_CREDENTIALS", "error_message": "the provided credentials were not correct", "display_message": "The provided credentials were not correct. Please try again.", "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_MFA  ##### The institution indicated that the provided response for MFA was invalid  ##### Sample user-facing error message  Your answers were incorrect: For security reasons, your account may be locked after several unsuccessful attempts ##### Link user experience  Your user will be redirected to the MFA pane to retry entering the correct value. ##### Common causes  * The user entered an incorrect answer for the security question presented by the selected institution. * The user selected an MFA device that is not active. * The institution failed to send the one-time code for the user's selected device. ##### Troubleshooting steps  If the user still cannot log in despite providing correct information, or if they cannot receive an MFA token despite having the correct device, please submit a 'Invalid credentials errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/invalid-creds) ticket with the following identifiers: `institution_id`, and either `link_session_id` or `request_id`. API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "INVALID_MFA", "error_message": "the provided MFA response(s) were not correct", "display_message": "The provided MFA responses were not correct. Please try again.", "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_SEND\_METHOD  ##### Returned when the method used to send MFA credentials was deemed invalid by the institution.  ##### Link user experience  Your user will be shown an error message indicating that an internal error occurred and will be prompted to close Link. ##### Common causes  * The institution is experiencing login issues. * The integration between Plaid and the financial institution is experiencing errors. ##### Troubleshooting steps  If the error persists, submit a 'Multi-factor authentication issues' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/mfa-issue) ticket with the following identifiers: `institution_id` and either `link_session_id` or `request_id`. API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "INVALID_SEND_METHOD", "error_message": "the provided MFA send_method was invalid", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_PHONE\_NUMBER  ##### The submitted phone number was invalid.  ##### Sample user-facing error message  Invalid phone number: We couldn't verify that 4151231234 is a valid number. Please re-enter your phone number to try again. ##### Link user experience  Your user will be redirected to the phone number input pane to retry submitting a valid phone number. ##### Common causes  * The user entered an invalid phone number. Only US and CA phone numbers are accepted for the [returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) . ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "INVALID_PHONE_NUMBER", "error_message": "the provided phone number was invalid", "display_message": "The provided phone number was invalid. Please try again.", "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_OTP  ##### The submitted OTP was invalid.  ##### Sample user-facing error message  Security code incorrect: Check that the code you entered is the same code that was sent to you ##### Link user experience  Your user will be redirected to the OTP input pane to retry submitting a valid OTP. After three `INVALID_OTP` errors, Link will stop accepting OTP inputs and the user will be prompted to exit Link or select another institution. If the flow was the Layer or Returning User Experience (Remember Me) flow, after the third invalid OTP code, instead of `INVALID_OTP`, the `PROFILE_AUTHENTICATION_FAILED` error will trigger, and Link will stop accepting OTP inputs. ##### Common causes  * The user entered an invalid OTP. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "INVALID_OTP", "error_message": "the provided OTP was invalid", "display_message": "The provided OTP was invalid. Please try again.", "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_UPDATED\_USERNAME  ##### The username entered during update mode did not match the original username.  ##### Sample user-facing error message  Username incorrect: Try entering your bank account username again. If you recently changed it, you may need to un-link your account and then re-link. ##### Link user experience  Your user will be directed to enter a different username. ##### Common causes  * While updating an Item in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) , the user provided a username that doesn't match the original username provided when they originally linked the account. * The user was updating an Item in update mode, but Plaid cannot verify that the new Item is the same as the original Item. This may be due to changes to the user's selections during the OAuth UI flow, changes in the `/link/token/create/` call parameters, or internal system changes at the financial institution. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "INVALID_UPDATED_USERNAME", "error_message": "the username provided to /item/credentials/update does not match the original username for the item", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### ITEM\_CONCURRENTLY\_DELETED  ##### This item was deleted while the operation was in progress.  ##### Common causes  * An Item was deleted via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) while a request for its data was in process. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "ITEM_CONCURRENTLY_DELETED", "error_message": "This item was deleted while the operation was in progress", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### ITEM\_LOCKED  ##### The financial institution indicated that the user's account is locked. The user will need to work with the institution directly to unlock their account.  ##### Sample user-facing error message  Too many attempts: We're unable to complete your request. Please log into your account on the financial institution's website to unlock or reset access and then try again. ##### Link user experience  Your user will be directed to a new window with the institution's homepage to unlock their account. Link will then display the Institution Select pane for the user to connect a different account. ##### Common causes  * The user entered their credentials incorrectly after more than 3-5 attempts, triggering the institution's fraud protection systems and locking the user's account. ##### Troubleshooting steps  If the user is persistently locked out of their institution, submit an 'Invalid credentials errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/invalid-creds) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`. API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "ITEM_LOCKED", "error_message": "the account is locked. prompt the user to visit the institution's site and unlock their account", "display_message": "The given account has been locked by the financial institution. Please visit your financial institution's website to unlock your account.", "request_id": "HNTDNrA8F1shFEW" } ``` #### ITEM\_LOGIN\_REQUIRED  ##### Additional input from the user is required to continue getting data for this Item.  ##### Sample user-facing error message  Username or password incorrect: If you've recently updated your account with this institution, be sure you're entering your updated credentials ##### Common causes  * The institution does not use an OAuth-based connection and the user changed their password. * The institution does not use an OAuth-based connection and the user changed their multi-factor settings, or their multi-factor authentication has expired. * The institution has undergone a migration from a non-OAuth-based connection to an OAuth-based connection. * The institution uses an OAuth-based connection and the user's consent is no longer valid, either because it has expired, or because the user revoked access. * The institution uses an OAuth-based connection that does not allow duplicate Items, but the user connected a duplicate Item to the same application. * (Sandbox only) The Item was created in the Sandbox environment and is over 30 days old. ##### Troubleshooting steps  If the error is legitimate, having the user authenticate again should generally return their Item to a healthy state without further intervention. If this error persists, please submit a [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`. API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "ITEM_LOGIN_REQUIRED", "error_message": "the login details of this item have changed (credentials, MFA, or required user action) and a user login is required to update this information. use Link's update mode to restore the item to a good state", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### ITEM\_NOT\_FOUND  ##### The Item you requested cannot be found. This Item does not exist, has been previously removed via /item/remove, or has had access removed by the user  ##### Common causes  * Item was previously removed via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . * The user has depermissioned or deleted their Item via [my.plaid.com](https://my.plaid.com) . * Plaid support has deleted the Item in response to a data deletion request from the user. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "ITEM_NOT_FOUND", "error_message": "The Item you requested cannot be found. This Item does not exist, has been previously removed via /item/remove, or has had access removed by the user.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### ITEM\_NOT\_SUPPORTED  ##### Plaid is unable to support this user's accounts due to restrictions in place at the financial institution.  ##### Sample user-facing error message  Account not currently supported: Your account is not currently supported. Please log in using a different account ##### Link user experience  Your user will be redirected to the Institution Select pane to connect a different account. ##### Common causes  * Plaid does not currently support the types of accounts for the connected Item, due to restrictions in place at the selected institution. * Plaid does not currently support the specific type of multi-factor authentication in place at the selected institution. * The credentials provided are for a 'guest' account or other account type with limited account access. * A processor partner token is being created or used, but the country, products, or account types associated with the Item are not supported by the processor partner. ##### Troubleshooting steps  If the error persists and none of the common causes above seem to apply, [contact support](https://dashboard.plaid.com/support/new/) . API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "ITEM_NOT_SUPPORTED", "error_message": "this account is currently not supported", "display_message": "The given account is not currently supported for this financial institution. We apologize for the inconvenience.", "request_id": "HNTDNrA8F1shFEW" } ``` #### MANUAL\_VERIFICATION\_REQUIRED  ##### Returned when a data request has been made for a product that requires the user to manually verify their Item via Link's update mode.  ##### Common causes  * [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) was called on an Item that could not be automatically verified. This can occur when the institution only supports verification through one of the [Investments Move fallback flows](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "MANUAL_VERIFICATION_REQUIRED", "error_message": "This Item could not be automatically verified. The user must manually verify their account through a separate Link session using the existing access token and with 'investments_auth' initialized in the 'products' array.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### MFA\_NOT\_SUPPORTED  ##### Returned when the user requires a form of MFA that Plaid does not support for a given financial institution.  ##### Sample user-facing error message  Your account settings are incompatible: Your account could not be connected because the multi-factor authentication method it uses is not currently supported. Please try a different account. ##### Link user experience  Your user will be redirected to the Institution Select pane to connect a different account. ##### Common causes  * Plaid does not currently support the specific type of multi-factor authentication in place at the selected institution. * The user's multi-factor authentication setting is configured not to remember trusted devices and instead to present a multi-factor challenge on every login attempt. This prevents Plaid from refreshing data asynchronously, which many products (especially Transactions) require. ##### Troubleshooting steps  If user's settings are not configured to present a multi-factor challenge on every login attempt but this error is still appearing, submit a 'Multi-factor authentication issues' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/mfa-issue) ticket with the following identifiers: `institution_id` and either `link_session_id` or `request_id`. API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "MFA_NOT_SUPPORTED", "error_message": "this account requires a MFA type that we do not currently support for the institution", "display_message": "The multi-factor security features enabled on this account are not currently supported for this financial institution. We apologize for the inconvenience.", "request_id": "HNTDNrA8F1shFEW" } ``` #### NO\_ACCOUNTS  ##### Returned when there are no open accounts associated with the Item.  ##### Sample user-facing error message  No compatible accounts: Your credentials are correct, but we couldn’t find any accounts with this institution that are compatible with this application. Try another account, financial institution, or check for another connection method. ##### Link user experience  Your user will be redirected to the Institution Select pane to connect a different account. ##### Common causes  * The user successfully logged into their account, but Plaid was unable to retrieve any open, active, or eligible accounts in the connected Item. * The user closed their account. * The user revoked access to the account. * The account experienced [account churn](https://plaid.com/docs/errors/invalid-input/index.html.md#account-churn) , which happens when Plaid can no longer recognize an account as the same one that the user granted you access to. When this happens, your permissions to the account may be revoked. * There is a problem with Plaid's connection to the user's financial institution. ##### Troubleshooting steps  If this error persists and the user does have accounts at the institution that you should be able to access, please submit a [Support](https://dashboard.plaid.com/support/new) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`. API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "NO_ACCOUNTS", "error_message": "no valid accounts were found for this item", "display_message": "No valid accounts were found at the financial institution. Please visit your financial institution's website to confirm accounts are available.", "request_id": "HNTDNrA8F1shFEW" } ``` #### NO\_AUTH\_ACCOUNTS or no-depository-accounts  ##### Returned from POST /auth/get when there are no valid accounts for which account and routing numbers could be retrieved.  ##### Sample user-facing error message  No eligible accounts: We didn't find any accounts eligible for money movement at this institution. Please try linking another institution ##### Common causes  * [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) was called on an Item with no accounts that can support Auth, or accounts that do support Auth were filtered out. Only debitable checking, savings, and cash management accounts can be used with Auth. * Plaid's ability to retrieve Auth data from the institution has been temporarily disrupted. * The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any compatible accounts. Note that for some institutions, the end user may need to specifically opt-in during the OAuth flow to share account and routing number information even if they have already opted in to sharing information about their checking or savings account. * The end user revoked access to the account. * The account experienced [account churn](https://plaid.com/docs/errors/invalid-input/index.html.md#account-churn) , which happens when Plaid can no longer recognize an account as the same one that the user granted you access to. When this happens, your permissions to the account may be revoked. ##### Troubleshooting steps  If the problem persists even though the end user has confirmed that they have a debitable checking, savings, or cash management account at the institution, [open a support ticket](https://dashboard.plaid.com/support/new) . API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "NO_AUTH_ACCOUNTS", "error_message": "There are no valid checking or savings account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### NO\_INVESTMENT\_ACCOUNTS  ##### Returned from POST /investments/holdings/get, POST /investments/transactions/get, or Link initialized with the Investments product, when there are no valid investment account(s) for which holdings or transactions could be retrieved.  ##### Sample user-facing error message  No investment accounts: None of your accounts are investment accounts. Please connect using a different bank ##### Common causes  * Link was initialized with the Investments product, but the user attempted to link an account with no investment accounts. * The [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) or [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) endpoint was called, but there are no investment accounts associated with the Item. * The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any investment accounts. ##### Troubleshooting steps  If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, [open a support ticket](https://dashboard.plaid.com/support/new) . API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "NO_INVESTMENT_ACCOUNTS", "error_message": "There are no valid investment account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### NO\_INVESTMENT\_AUTH\_ACCOUNTS  ##### Returned from POST /investments/holdings/get or POST /investments/transactions/get when there are no valid investment account(s) for which holdings or transactions could be retrieved.  ##### Common causes  * The [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) or [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) endpoint was called, but there are no investment accounts associated with the Item. * The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any investment accounts. ##### Troubleshooting steps  If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, [open a support ticket](https://dashboard.plaid.com/support/new) . API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "NO_INVESTMENT_AUTH_ACCOUNTS", "error_message": "There are no valid investment account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### NO\_LIABILITY\_ACCOUNTS  ##### Returned from POST /liabilities/get when there are no valid liability account(s) for which liabilities could be retrieved.  ##### Sample user-facing error message  No liability accounts: None of your accounts are liability accounts. Please connect using a different bank ##### Common causes  * The [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) endpoint was called, but there are no supported liability accounts associated with the Item. * The end user is connecting to an institution that uses OAuth-based flows but did not grant permission in the OAuth flow for the institution to share details for any liabilities accounts. ##### Troubleshooting steps  If the problem persists, Plaid may be erroneously categorizing the account. If this is the case, [open a support ticket](https://dashboard.plaid.com/support/new) . API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "NO_LIABILITY_ACCOUNTS", "error_message": "There are no valid liability account(s) associated with this Item. See https://plaid.com/docs/api/#item-errors for more information.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### PASSWORD\_RESET\_REQUIRED  ##### The user must log in directly to the financial institution and reset their password.  ##### Common causes  * The institution is blocking access because the user needs to reset their password. ##### Troubleshooting steps  Ask that the user log in to the bank, and confirm whether they are presented with a message to reset their password. If they are, they should follow the instructions to reset their password. Once the password is reset, they should attempt to link their account again. API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "PASSWORD_RESET_REQUIRED", "error_message": "user must reset their password", "display_message": "The user needs to reset their password for their account", "request_id": "HNTDNrA8F1shFEW" } ``` #### PRODUCT\_NOT\_ENABLED  ##### A requested product was not enabled for the current access token. Please ensure it is included when initializing Link and create the Item again.  ##### Common causes  * You requested a product that was not enabled for the current access token. Ensure it is included when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and create the Item again. API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "PRODUCT_NOT_ENABLED", "error_message": "A requested product was not enabled for the current access token. Please ensure it is included when when initializing Link and create the Item again.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### PRODUCT\_NOT\_READY  ##### Returned when a data request has been made for a product that is not yet ready.  For the Assets version of this error, see [ASSET\_REPORT\_ERROR: PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/assets/index.html.md#product_not_ready) . For the Income Verification version, see [INCOME\_VERIFICATION\_ERROR: PRODUCT\_NOT\_READY](https://plaid.com/docs/errors/income/index.html.md#product_not_ready) . ##### Common causes  * [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) was called before the first 30 days of transactions data could be extracted. This typically happens if the endpoint was called within a few seconds of linking the Item. It will also happen if [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) was called for the first time on an Item that was not initialized with `transactions` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. Note that this error does not occur when using [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) ; if called too early, [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) will simply fail to return any transactions. * Occasionally, this error can occur upon calling [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) if Plaid's attempt to extract transactions for the Item has failed, due to a connectivity error with the financial institution, and Plaid has never successfully extracted transactions for the Item in the past. If this happens, Plaid will continue to retry the extraction at least once a day. * [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) was called for the first time on a new Item before any balance data could be extracted for the Item. When called, [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) will return a `PRODUCT_NOT_READY` error if cached balance data does not exist and new balance data could not be obtained after 15 seconds. For some customers who participated in the early phases of the Signal beta, [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) will return `PRODUCT_NOT_READY` immediately if cached balance data is not available when [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) is called. * [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) was called on an Item that hasn't been verified, which is possible when using [micro-deposit based verification](https://plaid.com/docs/auth/coverage/index.html.md) . * [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) was called before the investments data could be extracted. This typically happens when the endpoint is called with the option for `async_update` set to true, and called again within a few seconds of linking the Item. It will also happen if [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) (with `async_update` set to true) was called for the first time on an Item that was not initialized with `investments` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "PRODUCT_NOT_READY", "error_message": "the requested product is not yet ready. please provide a webhook or try the request again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### PRODUCTS\_NOT\_SUPPORTED  ##### Returned when a data request has been made for an Item for a product that it does not support. Use the /item/get endpoint to find out which products an Item supports.  ##### Common causes  * A product endpoint request was made for an Item that does not support that product. This can happen when trying to call a product endpoint on an Item if the product was not included in either the `products` or `optional_products` arrays when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . * Updated accounts have been requested for an Item initialized with the Assets product, which does not support adding or updating accounts after the initial Link. * You are attempting to call [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) on a non-US financial institution. * You are attempting to call [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) on a manually linked Item (Database Insights, Database Match, Instant Micro-deposits, Same Day Micro-deposits) or on an Item that contains only limited purpose checking accounts. * You are attempting to call [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) on a Capital One Item that contains only credit cards or other non-depository products. Capital One does not support the [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) endpoint for non-depository products. * You are attempting to call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) on an Item that was manually linked (using Database Insights, Database Match, Instant Micro-deposits, or Same Day Micro-deposits) that has not been seen on the Plaid network before. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "PRODUCTS_NOT_SUPPORTED", "error_message": "", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### USER\_SETUP\_REQUIRED  ##### The user must log in directly to the financial institution and take some action before Plaid can access their accounts.  ##### Sample user-facing error message  Action required with your account: Log in to your bank and update your account. Then, return to Plaid to continue. ##### Link user experience  Your user will be directed to a new window with the institution's homepage to unlock their account. Link will then display the Institution Select pane for the user to connect a different account. ##### Common causes  * The institution requires special configuration steps before the user can link their account with Plaid. KeyBank, Morgan Stanley, Interactive Brokers, and Betterment are examples of institutions that require this setup. * The user's account is not fully set up at their institution. * The institution is blocking access due to an administrative task that requires completion. This error can arise for a number of reasons, the most common being: * The user must agree to updated terms and conditions. * The user must reset their password. * The user must enter additional account information. ##### Troubleshooting steps  Ask that the user log in to the bank, and confirm whether they are presented with some form of agreement page, modal, or some other actionable task. The user should also check their bank website for special settings to allow access for third-party apps, such as a "third party application password" or "allow third party access" setting. This can usually be done completely online, but there are some financial institutions that require the user to call a phone number, or access a physical branch. If the user is still unable to log in to their institution, please submit a 'Invalid credentials errors' [Support](https://dashboard.plaid.com/support/new/financial-institutions/authentication-issues/invalid-creds) ticket with the following identifiers: `access_token`, `institution_id`, and either `link_session_id` or `request_id`. API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "USER_SETUP_REQUIRED", "error_message": "the account has not been fully set up. prompt the user to visit the issuing institution's site and finish the setup process", "display_message": "The given account is not fully setup. Please visit your financial institution's website to setup your account.", "request_id": "HNTDNrA8F1shFEW" } ``` #### USER\_INPUT\_TIMEOUT  ##### The user did not complete a step in the Link flow, and it timed out.  ##### Sample user-facing error message  Session expired: Please re-enter your information to link your accounts. ##### Common causes  * Your user did not complete the account selection flow within five minutes. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "ITEM_ERROR", "error_code": "USER_INPUT_TIMEOUT", "error_message": "user must retry this operation", "display_message": "The application timed out waiting for user input", "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Microdeposits errors | Plaid Docs Micro-deposits Errors  ====================== #### Guide to troubleshooting micro-deposits errors  #### BANK\_TRANSFER\_ACCOUNT\_BLOCKED  ##### The bank transfer could not be completed because a previous transfer involving the same end-user account resulted in an error.  ##### Common causes  * Plaid cannot send micro-deposits to verify this account because it has flagged the account as not valid for use. This may happen, for example, because a previous attempt by Plaid to transfer funds to this end user account resulted in an "account frozen" or "invalid account number" error. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "BANK_TRANSFER_ERROR", "error_code": "BANK_TRANSFER_ACCOUNT_BLOCKED", "error_message": "bank transfer was blocked due to a previous ACH return on this account", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - OAuth errors | Plaid Docs OAuth Errors  ============= #### Guide to troubleshooting OAuth errors  For information on troubleshooting OAuth errors in Link not related to a specific error code, see [Link troubleshooting: OAuth not working](https://plaid.com/docs/link/troubleshooting/index.html.md#oauth-not-working) . #### INCORRECT\_OAUTH\_NONCE  ##### An incorrect OAuth nonce was supplied when re-initializing Link.  ##### Common causes  * During the OAuth flow, Link must be initialized, the user must be handed off to the institution's OAuth authorization page, and then Link must be re-initialized for the user to complete Link flow. This error can occur if a different nonce is supplied during the re-initialization process than was originally supplied to Link for the first initialization step. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "OAUTH_ERROR", "error_code": "INCORRECT_OAUTH_NONCE", "error_message": "nonce does not match", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INCORRECT\_LINK\_TOKEN  ##### An incorrect Link token was supplied when re-initializing Link.  ##### Common causes  * During the OAuth flow, Link must be initialized, the user must be handed off to the institution's OAuth authorization page, and then Link must be re-initialized for the user to complete Link flow. This error can occur if a different `link_token` is supplied during the re-initialization process than was originally supplied to Link for the first initialization step. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "OAUTH_ERROR", "error_code": "INCORRECT_LINK_TOKEN", "error_message": "link token does not match original link token", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### OAUTH\_STATE\_ID\_ALREADY\_PROCESSED  ##### The OAuth state has already been processed.  ##### Common causes  * During the OAuth flow, Link must be initialized, the user must be handed off to the institution's OAuth authorization page, and then Link must be re-initialized for the user to complete Link flow. This error can occur if the OAuth state ID used during re-initialization of Link has already been used. ##### Troubleshooting steps  API error response ```json http code 208 { "error_type": "OAUTH_ERROR", "error_code": "OAUTH_STATE_ID_ALREADY_PROCESSED", "error_message": null, "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### OAUTH\_STATE\_ID\_NOT\_FOUND  ##### The OAuth state id could not be found.  ##### Common causes  * An internal Plaid error occurred. ##### Troubleshooting steps  API error response ```json http code 404 { "error_type": "OAUTH_ERROR", "error_code": "OAUTH_STATE_ID_NOT_FOUND", "error_message": "the provided oauth_state_id wasn't found", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Partner errors | Plaid Docs Partner Errors  =============== #### Guide to troubleshooting partner errors  #### CUSTOMER\_NOT\_FOUND  ##### Customer not found  ##### Common causes  * The end customer could not be found. ##### Troubleshooting steps  API error response ```json http code 404 { "error_type": "PARTNER_ERROR", "error_code": "CUSTOMER_NOT_FOUND", "error_message": "the customer was not found", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### FLOWDOWN\_NOT\_COMPLETE  ##### Flowdown not complete  ##### Common causes  * A flowdown, which is a prerequisite for creating an end customer, has not been completed. ##### Troubleshooting steps  API error response ```json http code 412 { "error_type": "PARTNER_ERROR", "error_code": "FLOWDOWN_NOT_COMPLETE", "error_message": "you must complete a flowdown to create and enable customers", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### QUESTIONNAIRE\_NOT\_COMPLETE  ##### Questionnaire not complete  ##### Common causes  * A security questionnaire, which is a prerequisite for creating an end customer, has not been submitted. ##### Troubleshooting steps  API error response ```json http code 412 { "error_type": "PARTNER_ERROR", "error_code": "QUESTIONNAIRE_NOT_COMPLETE", "error_message": "you must complete the security questionnaire to create and enable customers", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### CUSTOMER\_NOT\_READY\_FOR\_ENABLEMENT  ##### Customer not ready for enablement  ##### Common causes  * The end customer requires manual approval from Plaid's Partnerships team. * The end customer has been denied access to the Plaid API. ##### Troubleshooting steps  API error response ```json http code 412 { "error_type": "PARTNER_ERROR", "error_code": "CUSTOMER_NOT_READY_FOR_ENABLEMENT", "error_message": "this customer is not ready for enablement", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### CUSTOMER\_ALREADY\_ENABLED  ##### Customer already enabled  ##### Common causes  * The end customer has already been enabled. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "PARTNER_ERROR", "error_code": "CUSTOMER_ALREADY_ENABLED", "error_message": "this customer has already been enabled", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### CUSTOMER\_ALREADY\_CREATED  ##### Customer already created  ##### Common causes  * The end customer has already been created. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "PARTNER_ERROR", "error_code": "CUSTOMER_ALREADY_CREATED", "error_message": "this customer has already been created", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### LOGO\_REQUIRED  ##### Logo required  ##### Common causes  * A logo is required for this customer because the `create_link_customization` field was set to `true` and the co-branded consent field is in use. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "PARTNER_ERROR", "error_code": "LOGO_REQUIRED", "error_message": "a logo is required because create_link_customization is set to true and the co-branded consent pane is in use", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_LOGO  ##### Invalid logo  ##### Common causes  * The logo is not a valid base64-encoded string of a PNG of size 1024x1024. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "PARTNER_ERROR", "error_code": "INVALID_LOGO", "error_message": "the logo must be a base64-encoded string of a PNG of size 1024x1024", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### CONTACT\_REQUIRED  ##### Contact required  ##### Common causes  * A billing or technical contact is required, either in the API request or in the Dashboard. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "PARTNER_ERROR", "error_code": "CONTACT_REQUIRED", "error_message": "billing or technical contacts must be submitted either in the request or filled in for your team in the dashboard", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### ASSETS\_UNDER\_MANAGEMENT\_REQUIRED  ##### Assets Under Management required  ##### Common causes  * The `assets_under_management` field is required because you have a monthly service commitment, but it was omitted from your API request. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "PARTNER_ERROR", "error_code": "ASSETS_UNDER_MANAGEMENT_REQUIRED", "error_message": "assets under management must be submitted because your team has a monthly service commitment", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### CUSTOMER\_REMOVAL\_NOT\_ALLOWED  ##### Removal not allowed  ##### Common causes  * You have attempted to remove an end customer that has already been enabled in the Production environment, which is not allowed. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "PARTNER_ERROR", "error_code": "CUSTOMER_REMOVAL_NOT_ALLOWED", "error_message": "removal of a production-enabled end customer is not allowed. talk to your account manager to remove this end customer.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### OAUTH\_REGISTRATION\_ERROR  ##### OAuth Registration Error  ##### Common causes  * End customer error encountered while registering with OAuth institutions. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "PARTNER_ERROR", "error_code": "OAUTH_REGISTRATION_ERROR", "error_message": "application logo is required", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Payment errors (Europe) | Plaid Docs Payment Errors  =============== #### Errors specific to the Payment Initiation product  #### PAYMENT\_BLOCKED  ##### The payment was blocked for violating compliance rules.  ##### Common causes  * The payment amount value when calling [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) was too high. * Too many payments were created in a short period of time. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "PAYMENT_ERROR", "error_code": "PAYMENT_BLOCKED", "error_message": "payment blocked", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### PAYMENT\_CANCELLED  ##### The payment was cancelled.  ##### Sample user-facing error message  Payment cancelled: Try making your payment again or select a different bank to continue. ##### Common causes  * The payment was cancelled by the user during the authorisation process ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "PAYMENT_ERROR", "error_code": "PAYMENT_CANCELLED", "error_message": "user cancelled the payment", "display_message": "Try making your payment again or select a different bank to continue.", "request_id": "HNTDNrA8F1shFEW" } ``` #### PAYMENT\_INSUFFICIENT\_FUNDS  ##### The account has insufficient funds to complete the payment.  ##### Sample user-facing error message  Insufficient funds: There isn't enough money in this account to complete the payment. Try again, or select another account or bank. ##### Common causes  * The account selected has insufficient funds to complete the payment. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "PAYMENT_ERROR", "error_code": "PAYMENT_INSUFFICIENT_FUNDS", "error_message": "insufficient funds to complete the request", "display_message": "There isn't enough money in this account to complete the payment. Try again, or select another account or bank.", "request_id": "HNTDNrA8F1shFEW" } ``` #### PAYMENT\_INVALID\_RECIPIENT  ##### The recipient was rejected by the chosen institution.  ##### Sample user-facing error message  Payment failed: Try making your payment again or select a different bank to continue. ##### Common causes  * The recipient name is too long or contains special characters. * The address is too long or contains special characters. * The account number is invalid. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "PAYMENT_ERROR", "error_code": "PAYMENT_INVALID_RECIPIENT", "error_message": "payment recipient invalid", "display_message": "The payment recipient is invalid for the selected institution. Create a new payment with a different recipient.", "request_id": "HNTDNrA8F1shFEW" } ``` #### PAYMENT\_INVALID\_REFERENCE  ##### The reference was rejected by the chosen institution.  ##### Sample user-facing error message  Payment failed: Try making your payment again or select a different bank to continue. ##### Common causes  * The reference is too long or contains special characters. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "PAYMENT_ERROR", "error_code": "PAYMENT_INVALID_REFERENCE", "error_message": "payment reference invalid", "display_message": "The payment reference is invalid for the selected institution. Create a new payment with a different reference.", "request_id": "HNTDNrA8F1shFEW" } ``` #### PAYMENT\_INVALID\_SCHEDULE  ##### The schedule was rejected by the chosen institution.  ##### Sample user-facing error message  Payment failed: Try making your payment again or select a different bank to continue. ##### Common causes  * The chosen institution does not support negative payment execution days. * The first payment date is a holiday or on a weekend. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "PAYMENT_ERROR", "error_code": "PAYMENT_INVALID_SCHEDULE", "error_message": "payment schedule invalid", "display_message": "The payment schedule is invalid for the selected institution. Create a new payment with a different schedule.", "request_id": "HNTDNrA8F1shFEW" } ``` #### PAYMENT\_REJECTED  ##### The payment was rejected by the chosen institution.  ##### Sample user-facing error message  Payment failed: Try making your payment again or select a different bank to continue. ##### Common causes  * The amount was too large. * The payment was considered suspicious by the institution. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "PAYMENT_ERROR", "error_code": "PAYMENT_REJECTED", "error_message": "payment rejected", "display_message": "The payment was rejected by the institution. Try again, or select another account or bank.", "request_id": "HNTDNrA8F1shFEW" } ``` #### PAYMENT\_SCHEME\_NOT\_SUPPORTED  ##### The requested payment scheme is not supported by the chosen institution.  ##### Sample user-facing error message  Payment failed: Try making your payment again or select a different bank to continue. ##### Common causes  * The payment scheme specified when calling [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) is not supported by the institution. * Scheme automatic downgrade failed. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "PAYMENT_ERROR", "error_code": "PAYMENT_SCHEME_NOT_SUPPORTED", "error_message": "payment scheme not supported", "display_message": "The payment scheme is not supported by the institution. Either change scheme or select another institution.", "request_id": "HNTDNrA8F1shFEW" } ``` #### PAYMENT\_CONSENT\_INVALID\_CONSTRAINTS  ##### The payment consent constraints are missing or not supported by the institution.  ##### Sample user-facing error message  Payment failed: Try making your payment again or select a different bank to continue. ##### Common causes  * The payment consent constraints specified when calling [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) are not supported by the institution. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "PAYMENT_ERROR", "error_code": "PAYMENT_CONSENT_INVALID_CONSTRAINTS", "error_message": "payment consent constraints invalid", "display_message": "The payment consent constraints are missing or not supported by the institution. Either update constraints or select another institution.", "request_id": "HNTDNrA8F1shFEW" } ``` #### PAYMENT\_CONSENT\_CANCELLED  ##### The payment consent was cancelled.  ##### Sample user-facing error message  Payment cancelled: Try setting up your payment again or select a different bank to continue ##### Common causes  * The payment consent was cancelled by the user during the authorisation process. ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 400 { "error_type": "PAYMENT_ERROR", "error_code": "PAYMENT_CONSENT_CANCELLED", "error_message": "user cancelled the payment consent", "display_message": "Authorise your payment consent again or select a different bank to continue.", "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Rate Limit Exceeded errors | Plaid Docs Rate Limit Exceeded Errors  =========================== #### Guide to troubleshooting rate limit exceeded errors  #### Rate limit table  Errors of type `RATE_LIMIT_EXCEEDED` will occur when the rate limit for a particular endpoint has been exceeded. Default rate limit thresholds for some of the most commonly rate-limited endpoints are shown below. Note that this table is not an exhaustive listing of all Plaid rate limits or rate-limited endpoints, that some customers may experience different rate limit thresholds from those shown, and that rate limits are subject to change at any time. In general, Plaid default rate limits are set such that using the API as designed should typically not cause a rate limit to be encountered. If your use case requires a higher rate limit, contact your account manager or file a [Support request](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/product-functionality) . ​ ​ ProductionSandbox Rate limits (Production) | Endpoint Toggle Sort Endpoint column, currently unsorted | Max requests per Item Toggle Sort Max requests per Item column, currently unsorted | Max requests per client Toggle Sort Max requests per client column, currently unsorted | | --- | --- | --- | | [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) | 5 per minute, 30 per hour | 1,200 per minute | | [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) | 15 per minute | 15,000 per minute | | [/asset\_report/audit\_copy/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copycreate) | N/A | 30 per minute | | [/asset\_report/audit\_copy/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportaudit_copyremove) | N/A | 30 per minute | | [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) | 5 per minute (per asset report) | 50 per minute | | [/asset\_report/filter](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportfilter) | N/A | 30 per minute | | [/asset\_report/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportget) | 15 per minute (per asset report) | 1,000 per minute | | [/asset\_report/pdf/get](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportpdfget) | 5 per minute (per asset report) | 50 per minute | | [/asset\_report/refresh](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportrefresh) | 5 per minute (per asset report) | 50 per minute | | [/asset\_report/remove](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportremove) | 15 per minute (per asset report) | 30 per minute | | [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) | 15 per minute | 12,000 per minute | | [/auth/verify](https://plaid.com/docs/api/products/auth/index.html.md#authverify) | N/A | 250 per minute | | [/bank\_transfer/balance/get](https://plaid.com/docs/bank-transfers/reference/index.html.md#bank_transferbalanceget) | N/A | 100 per minute | | [/bank\_transfer/cancel](https://plaid.com/docs/bank-transfers/reference/index.html.md#bank_transfercancel) | N/A | 30 per minute | | [/bank\_transfer/create](https://plaid.com/docs/bank-transfers/reference/index.html.md#bank_transfercreate) | N/A | 5,000 per minute | | [/bank\_transfer/event/list](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventlist) | N/A | 100 per minute | | [/bank\_transfer/event/sync](https://plaid.com/docs/api/products/auth/index.html.md#bank_transfereventsync) | N/A | 100 per minute | | [/bank\_transfer/get](https://plaid.com/docs/bank-transfers/reference/index.html.md#bank_transferget) | N/A | 100 per minute | | [/bank\_transfer/list](https://plaid.com/docs/bank-transfers/reference/index.html.md#bank_transferlist) | N/A | 100 per minute | | [/bank\_transfer/migrate\_account](https://plaid.com/docs/bank-transfers/reference/index.html.md#bank_transfermigrate_account) | N/A | 30 per minute | | [/beacon/duplicate/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconduplicateget) | N/A | 200 per minute | | [/beacon/report/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportcreate) | N/A | 60 per minute | | [/beacon/report/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportget) | N/A | 60 per minute | | [/beacon/report/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreportlist) | N/A | 60 per minute | | [/beacon/report\_syndication/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationget) | N/A | 60 per minute | | [/beacon/report\_syndication/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconreport_syndicationlist) | N/A | 60 per minute | | [/beacon/user/account\_insights/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuseraccount_insightsget) | N/A | 60 per minute | | [/beacon/user/create](https://plaid.com/docs/api/products/beacon/index.html.md#beaconusercreate) | N/A | 240 per minute | | [/beacon/user/get](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserget) | N/A | 60 per minute | | [/beacon/user/history/list](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserhistorylist) | N/A | 60 per minute | | [/beacon/user/update](https://plaid.com/docs/api/products/beacon/index.html.md#beaconuserupdate) | N/A | 120 per minute | | [/consent/events/get](https://plaid.com/docs/api/consent/index.html.md#consenteventsget) | N/A | 5,000 per minute | | [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) | N/A | 100 per minute (100 per user) | | [/cra/check\_report/cashflow\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcashflow_insightsget) | N/A | 100 per minute (100 per user) | | [/cra/check\_report/create](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportcreate) | N/A | 100 per minute | | [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) | N/A | 100 per minute (100 per user) | | [/cra/check\_report/lend\_score/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportlend_scoreget) | N/A | 100 per minute (100 per user) | | [/cra/check\_report/network\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportnetwork_insightsget) | N/A | 100 per minute (100 per user) | | [/cra/check\_report/partner\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpartner_insightsget) | N/A | 100 per minute (100 per user) | | [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) | N/A | 100 per minute (100 per user) | | [/cra/check\_report/verification/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationget) | N/A | 100 per minute | | [/cra/check\_report/verification/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportverificationpdfget) | N/A | 100 per minute | | [/cra/monitoring\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsget) | N/A | 100 per minute | | [/cra/monitoring\_insights/subscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightssubscribe) | N/A | 100 per minute | | [/cra/monitoring\_insights/unsubscribe](https://plaid.com/docs/api/products/check/index.html.md#cramonitoring_insightsunsubscribe) | N/A | 100 per minute | | [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) | N/A | 1,000 per minute | | [/credit/bank\_income/pdf/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomepdfget) | N/A | 1,000 per minute | | [/credit/bank\_statements/uploads/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_statementsuploadsget) | N/A | 1,000 per minute | | [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) | N/A | 1,000 per minute | | [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) | N/A | 1,000 per minute | | [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) | N/A | 20 per minute | | [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) | N/A | 1,000 per minute | | [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) | N/A | 1,000 per minute | | [/credit/relay/create](https://plaid.com/docs/api/products/assets/index.html.md#creditrelaycreate) | N/A | 15 per minute | | [/credit/relay/get](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayget) | N/A | 1,000 per minute | | [/credit/relay/refresh](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayrefresh) | N/A | 30 per minute | | [/credit/relay/remove](https://plaid.com/docs/api/products/assets/index.html.md#creditrelayremove) | N/A | 15 per minute | | [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) | N/A | 1,000 per minute | | [/dashboard\_user/get](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userget) | N/A | 2,000 per minute | | [/dashboard\_user/list](https://plaid.com/docs/api/kyc-aml-users/index.html.md#dashboard_userlist) | N/A | 2,000 per minute | | [/identity/documents/uploads/get](https://plaid.com/docs/api/products/identity/index.html.md#identitydocumentsuploadsget) | N/A | 2,000 per minute | | [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) | 15 per minute | 2,000 per minute | | [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) | 15 per minute | 2,000 per minute | | [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) | N/A | 120 per minute | | [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) | N/A | 420 per minute | | [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) | N/A | 300 per minute | | [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) | N/A | 120 per minute | | [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) | N/A | 50 per minute | | [/institutions/get\_by\_id](https://plaid.com/docs/api/institutions/index.html.md#institutionsget_by_id) | N/A | 400 per minute | | [/institutions/search](https://plaid.com/docs/api/institutions/index.html.md#institutionssearch) | N/A | 1,000 per minute | | [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) | 15 per minute | 500 per minute | | [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) | 15 per minute | 2,000 per minute | | [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) | 1 per minute, 10 per hour, 20 per day | 100 per minute, 6,000 per hour, 144,000 per day | | [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) | 30 per minute | 20,000 per minute | | [/item/access\_token/invalidate](https://plaid.com/docs/api/items/index.html.md#itemaccess_tokeninvalidate) | N/A | 20 per minute, 20 per minute | | [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) | 15 per minute | 5,000 per minute | | [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) | N/A | 12,000 per minute | | [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) | 20 per minute | 2,000 per minute | | [/item/webhook/update](https://plaid.com/docs/api/items/index.html.md#itemwebhookupdate) | 15 per minute | 5,000 per minute | | [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) | 30 per minute | 10,000 per minute | | [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) | N/A | 20,000 per minute | | [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) | N/A | 30,000 per minute | | [/network/status/get](https://plaid.com/docs/api/network/index.html.md#networkstatusget) | N/A | 1,000 per minute | | [/oauth/introspect](https://plaid.com/docs/api/oauth/index.html.md#oauthintrospect) | N/A | 20,000 per minute | | [/oauth/revoke](https://plaid.com/docs/api/oauth/index.html.md#oauthrevoke) | N/A | 20,000 per minute | | [/oauth/token](https://plaid.com/docs/api/oauth/index.html.md#oauthtoken) | N/A | 20,000 per minute | | [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) | N/A | 10 per minute | | [/partner/customer/enable](https://plaid.com/docs/api/partner/index.html.md#partnercustomerenable) | N/A | 10 per minute | | [/partner/customer/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomerget) | N/A | 60 per minute | | [/partner/customer/oauth\_institutions/get](https://plaid.com/docs/api/partner/index.html.md#partnercustomeroauth_institutionsget) | N/A | 100 per minute | | [/partner/customer/remove](https://plaid.com/docs/api/partner/index.html.md#partnercustomerremove) | N/A | 10 per minute | | [/payment\_initiation/consent/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentcreate) | N/A | 100 per minute | | [/payment\_initiation/consent/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentget) | N/A | 240 per minute | | [/payment\_initiation/consent/payment/execute](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentpaymentexecute) | N/A | 240 per minute (5 per consent) | | [/payment\_initiation/consent/revoke](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationconsentrevoke) | N/A | 100 per minute | | [/payment\_initiation/payment/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentcreate) | N/A | 240 per minute | | [/payment\_initiation/payment/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentget) | N/A | 240 per minute | | [/payment\_initiation/payment/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentlist) | N/A | 240 per minute | | [/payment\_initiation/payment/reverse](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationpaymentreverse) | N/A | 240 per minute | | [/payment\_initiation/recipient/create](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientcreate) | N/A | 240 per minute | | [/payment\_initiation/recipient/get](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientget) | N/A | 240 per minute | | [/payment\_initiation/recipient/list](https://plaid.com/docs/api/products/payment-initiation/index.html.md#payment_initiationrecipientlist) | N/A | 240 per minute | | [/processor/account/get](https://plaid.com/docs/api/processor-partners/index.html.md#processoraccountget) | 15 per minute | 15,000 per minute | | [/processor/auth/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorauthget) | 15 per minute | 12,000 per minute | | [/processor/balance/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorbalanceget) | 5 per minute, 30 per hour | 1,200 per minute | | [/processor/identity/get](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentityget) | 20 per minute | 2,000 per minute | | [/processor/identity/match](https://plaid.com/docs/api/processor-partners/index.html.md#processoridentitymatch) | 15 per minute | 10,000 per minute | | [/processor/investments/holdings/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentsholdingsget) | N/A | 10,000 per minute, 10,000 per minute | | [/processor/investments/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorinvestmentstransactionsget) | N/A | 10,000 per minute, 10,000 per minute | | [/processor/liabilities/get](https://plaid.com/docs/api/processor-partners/index.html.md#processorliabilitiesget) | N/A | 10,000 per minute | | [/processor/signal/decision/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignaldecisionreport) | N/A | 4,000 per minute | | [/processor/signal/evaluate](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalevaluate) | N/A | 1,200 per minute | | [/processor/signal/prepare](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalprepare) | N/A | 2,000 per minute | | [/processor/signal/return/report](https://plaid.com/docs/api/processor-partners/index.html.md#processorsignalreturnreport) | N/A | 4,000 per minute | | [/processor/stripe/bank\_account\_token/create](https://plaid.com/docs/api/processors/index.html.md#processorstripebank_account_tokencreate) | N/A | 100 per minute | | [/processor/token/create](https://plaid.com/docs/api/processors/index.html.md#processortokencreate) | N/A | 500 per minute | | [/processor/token/permissions/get](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsget) | N/A | 20 per minute | | [/processor/token/permissions/set](https://plaid.com/docs/api/processors/index.html.md#processortokenpermissionsset) | N/A | 500 per minute | | [/processor/token/webhook/update](https://plaid.com/docs/api/processor-partners/index.html.md#processortokenwebhookupdate) | N/A | 5,000 per minute | | [/processor/transactions/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsget) | 20 per minute, 20 per minute | 20,000 per minute | | [/processor/transactions/recurring/get](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrecurringget) | 15 per minute | 1,000 per minute | | [/processor/transactions/refresh](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionsrefresh) | 15 per minute | 500 per minute | | [/processor/transactions/sync](https://plaid.com/docs/api/processor-partners/index.html.md#processortransactionssync) | 50 per minute | 2,500 per minute | | [/sandbox/bank\_transfer/fire\_webhook](https://plaid.com/docs/bank-transfers/reference/index.html.md#sandboxbank_transferfire_webhook) | N/A | 100 per minute | | [/sandbox/bank\_transfer/simulate](https://plaid.com/docs/bank-transfers/reference/index.html.md#sandboxbank_transfersimulate) | N/A | 100 per minute | | [/sandbox/cra/cashflow\_updates/update](https://plaid.com/docs/api/sandbox/index.html.md#sandboxcracashflow_updatesupdate) | N/A | 30 per minute | | [/sandbox/income/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxincomefire_webhook) | N/A | 20 per minute | | [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) | 100 per minute | 500 per minute | | [/sandbox/item/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemreset_login) | 30 per minute | 500 per minute | | [/sandbox/item/set\_verification\_status](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemset_verification_status) | 30 per minute | 1,000 per minute | | [/sandbox/payment/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpaymentsimulate) | N/A | 100 per minute | | [/sandbox/processor\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxprocessor_tokencreate) | N/A | 30 per minute | | [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) | N/A | 30 per minute | | [/sandbox/transactions/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransactionscreate) | 2 per minute | 50 per minute | | [/sandbox/transfer/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferfire_webhook) | N/A | 100 per minute | | [/sandbox/transfer/ledger/deposit/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerdepositsimulate) | N/A | 10,000 per minute | | [/sandbox/transfer/ledger/simulate\_available](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgersimulate_available) | N/A | 10,000 per minute | | [/sandbox/transfer/ledger/withdraw/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferledgerwithdrawsimulate) | N/A | 10,000 per minute | | [/sandbox/transfer/refund/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransferrefundsimulate) | N/A | 20 per minute | | [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) | N/A | 100 per minute | | [/sandbox/transfer/test\_clock/advance](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockadvance) | N/A | 30 per minute | | [/sandbox/transfer/test\_clock/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockcreate) | N/A | 30 per minute | | [/sandbox/transfer/test\_clock/get](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clockget) | N/A | 30 per minute | | [/sandbox/transfer/test\_clock/list](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfertest_clocklist) | N/A | 30 per minute | | [/sandbox/user/reset\_login](https://plaid.com/docs/api/sandbox/index.html.md#sandboxuserreset_login) | N/A | 500 per minute (30 per user) | | [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) | N/A | 20,000 per minute | | [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) | N/A | 4,000 per minute | | [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) | 70 per hour, 10 per transaction per hour | 20 per second | | [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) | N/A | 2,000 per minute | | [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) | N/A | 4,000 per minute | | [/statements/download](https://plaid.com/docs/api/products/statements/index.html.md#statementsdownload) | N/A | 50 per minute | | [/statements/list](https://plaid.com/docs/api/products/statements/index.html.md#statementslist) | N/A | 100 per minute | | [/statements/refresh](https://plaid.com/docs/api/products/statements/index.html.md#statementsrefresh) | N/A | 50 per minute | | [/transactions/enrich](https://plaid.com/docs/api/products/enrich/index.html.md#transactionsenrich) | N/A | 100 per minute | | [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) | 30 per minute | 20,000 per minute | | [/transactions/recurring/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrecurringget) | 20 per minute | 1,000 per minute | | [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) | 2 per minute, 120 per hour, 2,880 per day | 100 per minute, 18,000 per hour, 432,000 per day | | [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) | 50 per minute | 2,500 per minute (500 per empty cursor request) | | [/transfer/authorization/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcancel) | N/A | 2,500 per minute | | [/transfer/authorization/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transferauthorizationcreate) | N/A | 2,500 per minute | | [/transfer/cancel](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercancel) | N/A | 250 per minute | | [/transfer/capabilities/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfercapabilitiesget) | N/A | 10,000 per minute | | [/transfer/configuration/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transferconfigurationget) | N/A | 100 per minute | | [/transfer/create](https://plaid.com/docs/api/products/transfer/initiating-transfers/index.html.md#transfercreate) | 1,000,000 per day | 2,500 per minute | | [/transfer/event/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventlist) | N/A | 100 per minute | | [/transfer/event/sync](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfereventsync) | N/A | 5,000 per minute | | [/transfer/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferget) | N/A | 5,000 per minute | | [/transfer/intent/create](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentcreate) | N/A | 5,000 per minute | | [/transfer/intent/get](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transferintentget) | N/A | 100 per minute | | [/transfer/ledger/deposit](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdeposit) | N/A | 10,000 per minute | | [/transfer/ledger/distribute](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerdistribute) | N/A | 20 per minute | | [/transfer/ledger/event/list](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgereventlist) | N/A | 100 per minute | | [/transfer/ledger/get](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerget) | N/A | 10,000 per minute | | [/transfer/ledger/withdraw](https://plaid.com/docs/api/products/transfer/ledger/index.html.md#transferledgerwithdraw) | N/A | 10,000 per minute | | [/transfer/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transferlist) | N/A | 100 per minute | | [/transfer/metrics/get](https://plaid.com/docs/api/products/transfer/metrics/index.html.md#transfermetricsget) | N/A | 100 per minute | | [/transfer/migrate\_account](https://plaid.com/docs/api/products/transfer/account-linking/index.html.md#transfermigrate_account) | N/A | 1,000 per minute | | [/transfer/originator/funding\_account/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorfunding_accountcreate) | N/A | 10,000 per minute | | [/transfer/originator/get](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorget) | N/A | 100 per minute | | [/transfer/originator/list](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferoriginatorlist) | N/A | 100 per minute | | [/transfer/platform/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformoriginatorcreate) | N/A | 5 per minute | | [/transfer/platform/person/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformpersoncreate) | N/A | 50 per minute | | [/transfer/platform/requirement/submit](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformrequirementsubmit) | N/A | 25 per minute | | [/transfer/recurring/cancel](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcancel) | N/A | 250 per minute | | [/transfer/recurring/create](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringcreate) | N/A | 5,000 per minute | | [/transfer/recurring/get](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringget) | N/A | 100 per minute | | [/transfer/recurring/list](https://plaid.com/docs/api/products/transfer/recurring-transfers/index.html.md#transferrecurringlist) | N/A | 100 per minute | | [/transfer/refund/cancel](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcancel) | N/A | 250 per minute | | [/transfer/refund/create](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundcreate) | N/A | 5,000 per minute | | [/transfer/refund/get](https://plaid.com/docs/api/products/transfer/refunds/index.html.md#transferrefundget) | N/A | 100 per minute | | [/transfer/sweep/get](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweepget) | N/A | 100 per minute | | [/transfer/sweep/list](https://plaid.com/docs/api/products/transfer/reading-transfers/index.html.md#transfersweeplist) | N/A | 100 per minute | | [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) | N/A | 1,200 per minute | | [/user/get](https://plaid.com/docs/api/users/index.html.md#userget) | N/A | 1,200 per minute | | [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) | N/A | 5,000 per minute | | [/user/items/remove](https://plaid.com/docs/api/users/index.html.md#useritemsremove) | N/A | 1,200 per minute | | [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) | N/A | 1,200 per minute | | [/user/update](https://plaid.com/docs/api/users/index.html.md#userupdate) | N/A | 30 per minute | | [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) | N/A | 1,000 per minute | | [/wallet/create](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletcreate) | N/A | 100 per minute | | [/wallet/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletget) | N/A | 100 per minute | | [/wallet/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#walletlist) | N/A | 100 per minute | | [/wallet/transaction/execute](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionexecute) | N/A | 100 per minute | | [/wallet/transaction/get](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionget) | N/A | 240 per minute | | [/wallet/transaction/list](https://plaid.com/docs/api/products/virtual-accounts/index.html.md#wallettransactionlist) | N/A | 100 per minute | | [/watchlist\_screening/entity/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentitycreate) | N/A | 1,600 per minute | | [/watchlist\_screening/entity/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityget) | N/A | 60 per minute | | [/watchlist\_screening/entity/history/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityhistorylist) | N/A | 60 per minute | | [/watchlist\_screening/entity/hit/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityhitlist) | N/A | 60 per minute | | [/watchlist\_screening/entity/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentitylist) | N/A | 1,800 per minute | | [/watchlist\_screening/entity/program/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityprogramget) | N/A | 60 per minute | | [/watchlist\_screening/entity/program/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityprogramlist) | N/A | 60 per minute | | [/watchlist\_screening/entity/review/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityreviewcreate) | N/A | 60 per minute | | [/watchlist\_screening/entity/review/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityreviewlist) | N/A | 60 per minute | | [/watchlist\_screening/entity/update](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningentityupdate) | N/A | 1,800 per minute | | [/watchlist\_screening/individual/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualcreate) | N/A | 1,800 per minute | | [/watchlist\_screening/individual/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualget) | N/A | 300 per minute | | [/watchlist\_screening/individual/history/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualhistorylist) | N/A | 60 per minute | | [/watchlist\_screening/individual/hit/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualhitlist) | N/A | 300 per minute | | [/watchlist\_screening/individual/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividuallist) | N/A | 1,800 per minute | | [/watchlist\_screening/individual/program/get](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualprogramget) | N/A | 60 per minute | | [/watchlist\_screening/individual/program/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualprogramlist) | N/A | 60 per minute | | [/watchlist\_screening/individual/review/create](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualreviewcreate) | N/A | 60 per minute | | [/watchlist\_screening/individual/review/list](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualreviewlist) | N/A | 60 per minute | | [/watchlist\_screening/individual/update](https://plaid.com/docs/api/products/monitor/index.html.md#watchlist_screeningindividualupdate) | N/A | 700 per minute | | [/webhook\_verification\_key/get](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md#get-webhook-verification-key) | N/A | 500 per minute | You're already on the first page. You're already on the first page. Page 1 You're already on the last page. You're already on the last page. #### ACCOUNTS\_LIMIT  ##### Too many requests were made to the /accounts/get endpoint.  ##### Common causes  * Too many requests were made in a short period of time. In Production, requests to `/accounts/get` are rate limited to 15 per minute (per Item) and 15,000 per minute (per client). In the Sandbox, they are rate limited to 100 per minute (per Item) and 5,000 per minute (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "ACCOUNTS_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### ACCOUNTS\_BALANCE\_GET\_LIMIT  ##### Too many requests were made to the /accounts/balance/get endpoint.  ##### Common causes  * Too many requests were made in a short period of time by a single client. In Production, requests to `/accounts/balance/get` are rate limited to 1,200 per minute (per client). In the Sandbox, they are rate limited to 1,200 per minute (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "ACCOUNTS_BALANCE_GET_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### AUTH\_LIMIT  ##### Too many requests were made to the /auth/get endpoint.  ##### Common causes  * Too many requests were made in a short period of time. In Production, requests to `/auth/get` are rate limited to 15 per minute (per Item) and 12,000 per minute (per client). In the Sandbox, they are rate limited to 100 per minute (per Item) and 500 per minute (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "AUTH_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### BALANCE\_LIMIT  ##### Too many requests were made to the /accounts/balance/get endpoint.  ##### Common causes  * Too many requests were made for a single Item in a short period of time. In Production, requests to `/accounts/balance/get` are rate limited to 5 per minute, 30 per hour (per Item). In the Sandbox, they are rate limited to 25 per minute, 1,500 per hour (per Item). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "BALANCE_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### CREDITS\_EXHAUSTED  ##### You have used up your free API usage allocation in Limited Production  ##### Common causes  * You ran out of free API calls for a given product in Limited Production. * You do not yet have Production access and hit the Item creation cap in Limited Production. ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "CREDITS_EXHAUSTED", "error_message": "Free usage exhausted, please request full Production access to continue using this product", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### IDENTITY\_LIMIT  ##### Too many requests were made to the /identity/get endpoint.  ##### Common causes  * Too many requests were made in a short period of time. In Production, requests to `/identity/get` are rate limited to 15 per minute (per Item) and 2,000 per minute (per client). In the Sandbox, they are rate limited to 100 per minute (per Item) and 1,000 per minute (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "IDENTITY_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INSTITUTIONS\_GET\_LIMIT  ##### Too many requests were made to the /institutions/get endpoint.  ##### Common causes  * Too many requests were made in a short period of time. In Production, requests to `/institutions/get` are rate limited to 50 per minute (per client). In the Sandbox, they are rate limited to 10 per minute (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "INSTITUTIONS_GET_LIMIT", "error_message": "rate limit exceeded for attempts to access \"institutions get by id\". please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INSTITUTIONS\_GET\_BY\_ID\_LIMIT  ##### Too many requests were made to the /institutions/get\_by\_id endpoint.  ##### Common causes  * Too many requests were made in a short period of time. In Production, requests to `/institutions/get_by_id` are rate limited to 400 per minute (per client). In the Sandbox, they are rate limited to 400 per minute (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "INSTITUTIONS_GET_BY_ID_LIMIT", "error_message": "rate limit exceeded for attempts to access \"institutions get by id\". please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INSTITUTION\_RATE\_LIMIT  ##### Too many requests were made to a given institution.  ##### Common causes  * Too many requests were made by Plaid in a short period of time to a given institution. Because each institution has unique rate limiting behavior, Plaid cannot provide exact details of how many requests are necessary to trigger this behavior. * This error will only trigger when calling API endpoints that request real-time data from the institution, such as [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) or [/transactions/refresh](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsrefresh) . * This institution-level limit is distinct from per-Item or per-client limits and is not applied to user-present traffic (e.g., within Link). * In some cases, the cause of the rate limit may be another client and may not be your client application's behavior. ##### Troubleshooting steps  If your client made a very large number of requests in a short time to a real-time endpoint such as [/accounts/balance/get](https://plaid.com/docs/api/products/signal/index.html.md#accountsbalanceget) at a single institution, consider adding logic to spread these requests over a longer time window. Use an exponential backoff retry algorithm to try your request again later. API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "INSTITUTION_RATE_LIMIT", "error_message": "The institution is currently receiving too many requests. Please try again later.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVESTMENT\_HOLDINGS\_GET\_LIMIT  ##### Too many requests were made to the /investments/holdings/get endpoint.  ##### Common causes  * Too many requests were made in a short period of time. In Production, requests to `/investments/holdings/get` are rate limited to 15 per minute (per Item) and 2,000 per minute (per client). In the Sandbox, they are rate limited to 100 per minute (per Item) and 1,000 per minute (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "INVESTMENT_HOLDINGS_GET_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVESTMENT\_TRANSACTIONS\_LIMIT  ##### Too many requests were made to the /investments/transactions/get endpoint.  ##### Common causes  * Too many requests were made in a short period of time. In Production, requests to `/investments/transactions/get` are rate limited to 30 per minute (per Item) and 20,000 per minute (per client). In the Sandbox, they are rate limited to 100 per minute (per Item) and 1,000 per minute (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "INVESTMENT_TRANSACTIONS_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### ITEM\_GET\_LIMIT  ##### Too many requests were made to the /item/get endpoint.  ##### Common causes  * Too many requests were made in a short period of time. In Production, requests to `/item/get` are rate limited to 15 per minute (per Item) and 5,000 per minute (per client). In the Sandbox, they are rate limited to 40 per minute (per Item) and 5,000 per minute (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "ITEM_GET_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### RATE\_LIMIT  ##### Too many requests were made.  ##### Common causes  * Too many requests were made in a short period of time. * Sandbox credentials (the username `user_good` or `user_custom`) were used to attempt to log in to Production. Because using these credentials in a live environment is a common misconfiguration, they are frequently subject to rate limiting. * A Link attempt was detected as potential attempted abuse. For example, this may occur if a user enters their credentials incorrectly too many times in a row. ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "RATE_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSACTIONS\_LIMIT  ##### Too many requests were made to a transactions endpoint such as/transactions/get or /transactions/refresh.  ##### Common causes  * Too many requests were made in a short period of time. In Production, requests to `/transactions/get` are rate limited to 30 per minute (per Item) and 20,000 per minute (per client). In the Sandbox, they are rate limited to 30 per minute (per Item) and 1,000 per minute (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "TRANSACTIONS_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSACTIONS\_REFRESH\_LIMIT  ##### Too many requests were made to the /transactions/refresh endpoint.  ##### Common causes  * Too many requests were made in a short period of time. In Production, requests to `/transactions/refresh` are rate limited to 2 per minute, 120 per hour, 2,880 per day (per Item) and 100 per minute, 18,000 per hour, 432,000 per day (per client). In the Sandbox, they are rate limited to 2 per minute, 120 per hour, 2,880 per day (per Item) and 100 per minute, 6,000 per hour, 144,000 per day (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "TRANSACTIONS_REFRESH_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSACTIONS\_SYNC\_LIMIT  ##### Too many requests were made to the /transactions/sync endpoint.  ##### Common causes  * Too many requests were made in a short period of time. In Production, requests to `/transactions/sync` are rate limited to 50 per minute (per Item) and 2,500 per minute (500 per empty cursor request) (per client). In the Sandbox, they are rate limited to 50 per minute (per Item) and 1,000 per minute (250 per empty cursor request) (per client). ##### Troubleshooting steps  API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "TRANSACTIONS_SYNC_LIMIT", "error_message": "rate limit exceeded for attempts to access this item. please try again later", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRIAL\_CONNECTION\_LIMIT  ##### The Plaid Trial plan connection limit has been reached.  ##### Sample user-facing error message  Trial Connection Limit Exceeded: Plaid trial plan connection limit reached. The app developer must upgrade to full production access to continue adding bank connections. ##### Common causes  * Your application is on a Plaid Trial plan and has exceeded the maximum number of allowed bank connections (Items). ##### Troubleshooting steps  API error responseLink error preview API error response ```json http code 429 { "error_type": "RATE_LIMIT_EXCEEDED", "error_code": "TRIAL_CONNECTION_LIMIT", "error_message": "Trial connection limit exceeded. Upgrade to Production access to continue adding bank connections.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Recaptcha errors | Plaid Docs ReCAPTCHA Errors  ================= #### Guide to troubleshooting reCAPTCHA errors  #### RECAPTCHA\_REQUIRED  ##### The request was flagged by Plaid's fraud system, and requires additional verification to ensure they are not a bot.  ##### Link user experience  Your user will be prompted to solve a [Google reCAPTCHA](https://www.google.com/recaptcha/intro/v3.html) challenge in the Link `Recaptcha` pane. If they solve the challenge successfully, the user's request is resubmitted and they are directed to the next Item creation step. ##### Common causes  * Plaid's fraud system detects abusive traffic and considers a variety of parameters throughout Item creation requests. When a request is considered risky or possibly fraudulent, Link presents a reCAPTCHA for the user to solve. ##### Troubleshooting steps  Link will automatically guide your user through reCAPTCHA verification. As a general rule, we recommend instrumenting basic fraud monitoring to detect and protect your website from spam and abuse. If your user cannot verify their session, please submit a [Support](https://dashboard.plaid.com/support/new) ticket with the following identifiers: `link_session_id` or `request_id`. API error response ```json http code 400 { "error_type": "RECAPTCHA_ERROR", "error_code": "RECAPTCHA_REQUIRED", "error_message": "This request requires additional verification. Please resubmit the request after completing the challenge", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### RECAPTCHA\_BAD  ##### The provided challenge response was denied.  ##### Sample user-facing error message  Please try connecting a different account: There was a problem processing your request. Your account could not be connected at this time ##### Link user experience  If after several failed attempts your user is still unable to solve the reCAPTCHA challenge, the `RECAPTCHA_BAD` error is returned and they are directed to the `InstitutionSelect` pane to connect a new account. ##### Common causes  * The user was unable to successfully solve the presented reCAPTCHA problem after several attempts. * The current session is a bot or other malicious software. ##### Troubleshooting steps  If your user cannot verify their session, please submit a [Support](https://dashboard.plaid.com/support/new) ticket with the following identifiers: `link_session_id` or `request_id`. API error responseLink error preview API error response ```json http code 400 { "error_type": "RECAPTCHA_ERROR", "error_code": "RECAPTCHA_BAD", "error_message": "The provided challenge response was denied. Please try again", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Sandbox errors | Plaid Docs Sandbox Errors  =============== #### Guide to troubleshooting Sandbox errors  #### SANDBOX\_PRODUCT\_NOT\_ENABLED  ##### The requested product is not enabled for an Item  ##### Common causes  * A Sandbox operation could not be performed because a product has not been enabled on the Sandbox Item. ##### Troubleshooting steps  If the error persists, submit a [Support](https://dashboard.plaid.com/support/new/) ticket. API error response ```json http code 400 { "error_type": "SANDBOX_ERROR", "error_code": "SANDBOX_PRODUCT_NOT_ENABLED", "error_message": "The [auth | transactions | ...] product is not enabled on this item", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### SANDBOX\_WEBHOOK\_INVALID  ##### The request to fire a Sandbox webhook failed.  ##### Common causes  * The webhook for the Item sent in the [/sandbox/item/fire\_webhook](https://plaid.com/docs/api/sandbox/index.html.md#sandboxitemfire_webhook) request is not set or is invalid. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "SANDBOX_ERROR", "error_code": "SANDBOX_WEBHOOK_INVALID", "error_message": "Webhook for this item is either not set up, or invalid. Please update the item's webhook and try again.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### SANDBOX\_TRANSFER\_EVENT\_TRANSITION\_INVALID  ##### The /sandbox/transfer/simulate endpoint was called with parameters specifying an invalid event transition.  ##### Common causes  * The [/sandbox/transfer/simulate](https://plaid.com/docs/api/sandbox/index.html.md#sandboxtransfersimulate) endpoint was called with parameters specifying an invalid event transition. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "SANDBOX_ERROR", "error_code": "SANDBOX_TRANSFER_EVENT_TRANSITION_INVALID", "error_message": "The provided simulated event type is incompatible with the current transfer status", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Signal errors | Plaid Docs Signal errors  ============== #### Guide to troubleshooting Signal errors  #### ADDENDUM\_NOT\_SIGNED  ##### Signal-only actions were taken, but the client has not signed the Signal Addendum.  ##### Common causes  * A customer who was enabled for Balance before October 15, 2025 and is not enabled for Signal Transaction Scores called [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) , called [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) , or called [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) with the `device` or `user` fields populated. ##### Troubleshooting steps  API error response ```json http code 403 { "error_type": "SIGNAL_ERROR", "error_code": "ADDENDUM_NOT_SIGNED", "error_message": "The Signal Addendum has not been signed", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### CLIENT\_TRANSACTION\_ID\_ALREADY\_IN\_USE  ##### The client\_transaction\_id value specified is not unique  ##### Common causes  * When calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , the specified `client_transaction_id` has already been used. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "SIGNAL_ERROR", "error_code": "CLIENT_TRANSACTION_ID_ALREADY_IN_USE", "error_message": "Client transaction id has already been used in a different transaction", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INVALID\_CONFIGURATION\_STATE  ##### /signal/evaluate was called by a client whose Signal Rules configuration settings are in an invalid state  ##### Common causes  * A customer who is not enabled for Signal Transaction Scores called [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) with no ruleset key specified, while opted out of the default ruleset. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "SIGNAL_ERROR", "error_code": "INVALID_CONFIGURATION_STATE", "error_message": "Client configuration state is missing default ruleset imputation, contact your Account Manager for assistance.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### NOT\_ENABLED\_FOR\_SIGNAL\_TRANSACTION\_SCORE\_RULESETS  ##### A ruleset was specified that uses Signal Transaction Scores, but the customer is only enabled for Balance-only rulesets  ##### Common causes  * A customer who has previously used Signal Transaction Scores, but has since downgraded to Balance-only, attempted to use a ruleset that requires Signal Transaction Scores when calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) . ##### Troubleshooting steps  API error response ```json http code 403 { "error_type": "SIGNAL_ERROR", "error_code": "NOT_ENABLED_FOR_SIGNAL_TRANSACTION_SCORE_RULESETS", "error_message": "Your account is not enabled for Signal Transaction Score rulesets. Use a Balance-only ruleset or contact your Account Manager to enable Signal Transaction Scores.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### RULESET\_NOT\_FOUND  ##### The specified ruleset was not found  ##### Common causes  * When calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , no `ruleset_key` was specified, and the default ruleset has not been created. * When calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) , a `ruleset_key` was specified, and no matching ruleset could be found. * When switching between Sandbox and Production, a `ruleset_key` was specified that exists only in Sandbox or only in Production. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "SIGNAL_ERROR", "error_code": "RULESET_NOT_FOUND", "error_message": "Missing 'default' ruleset. Create the ruleset here: https://dashboard.plaid.com/signal/risk-profiles", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### SIGNAL\_TRANSACTION\_NOT\_INITIATED  ##### A return was reported on a transaction that was also reported never to have happened.  ##### Common causes  * A return was reported on the transaction using [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) , but [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) was already called for the same transaction with a value of `initiated: false`. * A return was reported on the transaction using [/signal/return/report](https://plaid.com/docs/api/products/signal/index.html.md#signalreturnreport) , but the Signal Ruleset evaluation indicated a value of `REROUTE` for the transaction and [/signal/decision/report](https://plaid.com/docs/api/products/signal/index.html.md#signaldecisionreport) was never called with a value of `initiated: true`. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "SIGNAL_ERROR", "error_code": "SIGNAL_TRANSACTION_NOT_INITIATED", "error_message": "Transactions previously reported as not initiated cannot be reported as returned", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Transactions errors | Plaid Docs Transactions errors  ==================== #### Guide to troubleshooting Transactions errors  #### TRANSACTIONS\_SYNC\_MUTATION\_DURING\_PAGINATION  ##### Transaction data was updated during pagination.  ##### Common causes  * Transaction data was updated during pagination. This can occur when calling the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSACTIONS_ERROR", "error_code": "TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION", "error_message": "Underlying transaction data changed since last page was fetched. Please restart pagination from last update.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Transfer errors | Plaid Docs Transfer errors  ================ #### Errors specific to the Transfer product  #### TRANSFER\_NETWORK\_LIMIT\_EXCEEDED  ##### The attempted transfer exceeded the given network's amount limit.  ##### Common causes  * The attempted transfer's amount exceeded the network specific limit. The error message will indicate which network limit was exceeded. For reference, see the table below. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSFER_ERROR", "error_code": "TRANSFER_NETWORK_LIMIT_EXCEEDED", "error_message": "[network] transaction amount cannot exceed [amount]", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` | Network | Maximum Transaction Limit | | --- | --- | | ACH | $10,000,000.00 | | Same Day ACH | $1,000,000.00 | | RTP | $1,000,000.00 | | RfP | $3,500.00 | | Wire | $999,999.99 | #### TRANSFER\_ACCOUNT\_BLOCKED  ##### The transfer could not be completed because a previous transfer involving the same end-user account resulted in an error  ##### Common causes  * Plaid has flagged the end-user's account as not valid for use with Transfer. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSFER_ERROR", "error_code": "TRANSFER_ACCOUNT_BLOCKED", "error_message": "transfer was blocked due to a previous ACH return on this account", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSFER\_NOT\_CANCELLABLE  ##### The transfer could not be canceled  ##### Common causes  * An attempt was made to cancel a transfer that has already been sent to the network for execution and cannot be cancelled at this stage. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSFER_ERROR", "error_code": "TRANSFER_NOT_CANCELLABLE", "error_message": "transfer is not cancellable", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSFER\_UNSUPPORTED\_ACCOUNT\_TYPE  ##### An attempt was made to transfer funds to or from an unsupported account type  ##### Common causes  * An attempt was made to transfer funds to or from an unsupported account type. Only checking, savings, and cash management accounts can be used with Transfer. In addition, if the transfer is a debit transfer, the account must be a debitable account. Common examples of non-debitable depository accounts include savings accounts at Chime or at Navy Federal Credit Union (NFCU). ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSFER_ERROR", "error_code": "TRANSFER_UNSUPPORTED_ACCOUNT_TYPE", "error_message": "transfer account type not supported", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSFER\_FORBIDDEN\_ACH\_CLASS  ##### An attempt was made to create a transfer with a forbidden ACH class (SEC code)  ##### Common causes  * Your Plaid account has not been enabled for the ACH class specified in the request. * The ACH class specified in the transfer request was incorrect. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSFER_ERROR", "error_code": "TRANSFER_FORBIDDEN_ACH_CLASS", "error_message": "specified ach_class is forbidden", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSFER\_UI\_UNAUTHORIZED  ##### The client is not enabled for the Transfer UI product  ##### Common causes  * Your account is not enabled for use with Transfer UI. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSFER_ERROR", "error_code": "TRANSFER_UI_UNAUTHORIZED", "error_message": "client is not authorized for transfer UI", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSFER\_ORIGINATOR\_NOT\_FOUND  ##### An association between the sender and the originator client doesn't exist  ##### Common causes  * There is a typo in the `originator_client_id` * You are a Transfer for Platforms customer (not a partner) and did not call [/transfer/platform/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformoriginatorcreate) for this end-customer ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSFER_ERROR", "error_code": "TRANSFER_ORIGINATOR_NOT_FOUND", "error_message": "the association between the sender and the originator client doesn't exist", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### INCOMPLETE\_CUSTOMER\_ONBOARDING  ##### The end customer has not completed onboarding. Their diligence status must be approved before moving funds  ##### Common causes  * You tried to move funds for an originator that hasn't been approved by Plaid yet ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSFER_ERROR", "error_code": "INCOMPLETE_CUSTOMER_ONBOARDING", "error_message": "end customer has not completed onboarding. their diligence status must be `approved` before moving funds", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### UNAUTHORIZED\_ACCESS  ##### You are not authorized to access this endpoint for your use case  ##### Common causes  * You are not a Transfer for Platforms customer and tried to call a platform-only endpoint * You are a Plaid Partner and tried to create an end-customer using [/transfer/platform/originator/create](https://plaid.com/docs/api/products/transfer/platform-payments/index.html.md#transferplatformoriginatorcreate) (instead of [/partner/customer/create](https://plaid.com/docs/api/partner/index.html.md#partnercustomercreate) ) ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSFER_ERROR", "error_code": "UNAUTHORIZED_ACCESS", "error_message": "you are not authorized to access this endpoint for your use case.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### ACH return codes  Prefer to learn by watching? A [video guide](https://www.youtube.com/watch?v=7UqU2TGLiMc) is available for this topic. All `returned` ACH transactions will have an ACH return code. By reading the code, you can troubleshoot and debug returned transactions. [Transfer](https://plaid.com/docs/transfer/index.html.md) customers should see [Common ACH Return Codes in the Help Center](https://support.plaid.com/hc/en-us/articles/32881797799575-What-are-the-Common-ACH-Return-Codes) for more detailed information on troubleshooting ACH return codes. | Return Code | Description | Notes | | --- | --- | --- | | R01 | Insufficient funds | Available balance is not sufficient to cover the dollar amount of the debit entry | | R02 | Account closed | A previously open account is now closed | | R03 | No account or unable to locate account | The account number structure is valid, but the account number does not correspond to an existing account, or the name on the transaction does not match the name on the account. | | R04 | Invalid account number | The account number fails the check digit validation or may contain an incorrect number of digits. Commonly caused by invalidated TANs; see [Tokenized account numbers](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) for more details. | | R05 | Unauthorized debit to consumer account | A business debit entry was transmitted to a member's consumer account, and the member had not authorized the entry | | R06 | Returned per ODFI's request | The ODFI has requested that the RDFI return the entry | | R07 | Authorization revoked by customer | Member who previously authorized an entry has revoked authorization with the originator | | R08 | Payment stopped or stop payment on item | Member had previously requested a stop payment of a single or recurring entry | | R09 | Uncollected funds | Available balance is sufficient, but the collected balance is not sufficient to cover the entry | | R10 | Customer advises not authorized | Member advises not authorized, notice not provided, improper source document, or amount of entry not accurately obtained from source document | | R11 | Check truncation entry return | To be used when returning a check truncation entry | | R12 | Branch sold to another DFI | RDFI unable to post entry destined for a bank account maintained at a branch sold to another financial institution | | R13 | Invalid ACH routing number | Financial institution does not receive commercial ACH entries | | R14 | Representative payee deceased or unable to continue in that capacity | Representative payee is deceased or unable to continue in that capacity, beneficiary is not deceased | | R15 | Beneficiary of account holder deceased | Beneficiary or Account Holder Deceased | | R16 | Account frozen | Access to account is restricted due to a specific action taken by the RDFI or by legal action | | R17 | File record edit criteria | Fields rejected by RDFI processing (identified in return addenda) | | R18 | Improper effective entry | Entries have been presented prior to the first available processing window for the effective date | | R19 | Amount field error | Improper formatting of the amount field | | R20 | Non-transaction account | Policies or regulations (such as Regulation D) prohibit or limit activity to the account indicated | | R21 | Invalid company identification | The company ID information not valid (normally CIE entries) | | R22 | Invalid individual ID number | Individual id used by receiver is incorrect (CIE entries) | | R23 | Credit entry refused by receiver | Receiver returned entry because minimum or exact amount not remitted, bank account is subject to litigation, or payment represents an overpayment, originator is not known to receiver or receiver has not authorized this credit entry to this bank account | | R24 | Duplicate entry | RDFI has received a duplicate entry | | R25 | Addenda error | Improper formatting of the addenda record information | | R26 | Mandatory field error | Improper information in one of the mandatory fields | | R27 | Trace number error | Original entry trace number is not valid for return entry; or addenda trace numbers do not correspond with entry detail record | | R28 | Routing number or check digit | Check digit for transit routing number is incorrect | | R29 | Corporate customer advises not authorized | RDFI has been notified by business account holder that a specific transaction is unauthorized. Business accounts often automatically decline debits for security purposes. Your customer needs to inform their bank to allow debits that use your tax identifier. | | R30 | RDFI not participant in check truncation program | Financial institution not participating in automated check safekeeping application | | R31 | Permissible return entry | RDFI has been notified by business account holder that a specific transaction is unauthorized | | R32 | RDFI non settlement | RDFI is not able to settle the entry | | R33 | Return of XCK entry | RDFI determines at its sole discretion to return an XCK entry; an XCK return entry may be initiated by midnight of the sixtieth day following the settlement date if the XCK entry | | R34 | Limited participation DFI | RDFI participation has been limited by a federal or state supervisor | | R35 | Return of improper debit entry | ACH debit not permitted for use with the CIE standard entry class code (except for reversals) | | R36 | Return of improper credit entry | | | R37 | Source Document Presented for Payment | Check used for an ARC, BOC or POP entry has also been presented for payment | | R38 | Stop payment on source document | Stop payment has been placed on a check used for an ARC entry | | R40 | Return of ENR entry by federal government agency (ENR only) | | | R41 | Invalid transaction code (ENR only) | | | R42 | Routing number or check digit error (ENR only) | | | R43 | Invalid DFI account number (ENR only) | | | R44 | Invalid individual ID number (ENR only) | | | R45 | Invalid individual name/company name (ENR only) | | | R46 | Invalid representative payee indicator (ENR only) | | | R47 | Duplicate enrollment | | | R50 | State law affecting RCK acceptance | | | R51 | Item is ineligible, notice not provided, signature not genuine | | | R52 | Stop payment on item | | | R61 | Misrouted return | Return entry was sent by RDFI to an incorrect ODFI routing/transit number | | R62 | Incorrect trace number | | | R63 | Incorrect dollar amount | | | R64 | Incorrect individual identification | | | R65 | Incorrect transaction code | | | R66 | Incorrect company identification | | | R67 | Duplicate return | ODFI has received more than one return entry for the same original entry | | R68 | Untimely return | Return entry did not meet the return deadline | | R69 | Multiple errors | | | R70 | Permissible return entry not accepted | | | R71 | Misrouted dishonored return | | | R72 | Untimely dishonored return | | | R73 | Timely original return | | | R74 | Corrected return | | | R80 | Cross-border payment coding error | | | R81 | Nonparticipant in cross-border program | | | R82 | Invalid foreign receiving DFI identification | | #### RTP/RfP error codes  `failed` RTP/RfP transactions will have a failure description. By reading the description, you can troubleshoot and debug failed transactions. This table can also be [viewed as a Google doc](https://docs.google.com/spreadsheets/d/12jHY-VZYtYqzSHQE6eEzy_I7ZbN4SLZcWTcdjoMAiuQ/edit?gid=123470926#gid=123470926) . | Failure Code | Description | Rail(s) | Condensed Error Category | Retryable | Suggested Action | | --- | --- | --- | --- | --- | --- | | 1100 | Other Reasons - Not specified | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. | | 9909 | Central Switch system malfunction | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. | | 9910 | Instructed Agent signed-off | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. | | 9912 | Recipient connection unavailable | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. | | 9934 | Instructing Agent signed-off | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. | | 9946 | Instructing Agent suspended | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. | | 9947 | Instructed Agent suspended | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. | | 9948 | Central Switch service suspended | RTP | Network issue (retryable) | Yes - auto‑retry | Wait briefly and retry automatically; consider fallback rail if urgent. | | AC02 | Debtor account is invalid | Both | Issues with the sending account | No | Ask the sender to correct or switch accounts, then resubmit. | | AC03 | Creditor account is invalid | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. | | AC04 | Account closed | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. | | AC06 | Account is blocked | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. | | AC07 | Creditor account closed | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. | | AC13 | Debtor account type invalid | Both | Issues with the sending account | No | Ask the sender to correct or switch accounts, then resubmit. | | AC14 | Creditor account type invalid | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. | | AG01 | Transaction forbidden on this type of account | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. | | AG03 | Transaction type not supported on this account | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. | | AM02 | Transaction amount exceeds allowed maximum | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | AM04 | Insufficient funds | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | AM09 | Incorrect amount received | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | AM12 | Amount invalid or missing | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | AM13 | Amount exceeds clearing system limits | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | AM14 | Amount exceeds bank-client limit | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | BE04 | Missing or incorrect creditor address | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. | | BE06 | End customer not known | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. | | BE07 | Missing or incorrect debtor address | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. | | BE16 | Debtor identification invalid | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. | | BE17 | Creditor identification invalid | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. | | BLKD | Payment has been blocked | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. | | CH11 | Creditor identifier unknown | RFP | Authorization declined or customer action required | No | Respect customer's decision or obtain new authorization. | | CUST | Customer declined payment | Both | Authorization declined or customer action required | No | Respect customer's decision or obtain new authorization. | | DS04 | Order rejected – content issues | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | DS0H | Signer not authorized for this account | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | DS24 | Waiting time expired (incomplete order) | Both | Authorization declined or customer action required | Yes - after correction | Respect customer's decision or obtain new authorization. | | DT04 | Future date not supported | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | DUPL | Duplicate payment detected | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | E997 | Timeout clock has expired | Both | Network issue (retryable) | Yes - after correction | Retry the payment with a different idempotency key. | | FF02 | Syntax error in narrative information | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | FF03 | Invalid payment type information | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | FF08 | End‑to‑End ID missing or invalid | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | INSF | Insufficient funds for outbound message | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | MD07 | End customer is deceased | Both | Beneficiary or compliance information issue | No | Investigate beneficiary data or compliance issues; do not auto‑retry. | | NARR | Narrative reason provided | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | NOAT | Account does not support this message type | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. | | RC01 | Bank identifier format incorrect | Both | Routing or bank identifier issue | Yes - after correction | Supply a valid routing/BIC and retry. | | RC02 | Bank identifier invalid or missing | Both | Routing or bank identifier issue | Yes - after correction | Supply a valid routing/BIC and retry. | | RC03 | Debtor FI identifier invalid or missing | Both | Routing or bank identifier issue | Yes - after correction | Supply a valid routing/BIC and retry. | | RC04 | Creditor FI identifier invalid or missing | Both | Issues with the receiving account (invalid, closed, blocked) | No | Request updated recipient account details or use another payout account. | | SL12 | Debtor opted out of RFPs | RFP | Authorization declined or customer action required | No | Respect customer's decision or obtain new authorization. | | TK01 | Invalid token | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | TK02 | Sender token not found | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | TK03 | Receiver token not found | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | TK04 | Token expired | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | TK05 | Token counterparty mismatch | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | TK06 | Token value‑limit rule violation | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | TK07 | Single‑use token already used | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | | TK08 | Token suspended | Both | Issues with payment details (amount, currency, token, duplicate, format) | Yes - after correction | Correct the payment amount, currency, token or format, then retry. | --- # Errors - User errors | Plaid Docs User Errors  ============ #### Guide to troubleshooting User errors  #### USER\_NOT\_FOUND  ##### The provided user\_id could not be found.  ##### Common causes  * The `user_id` was never created. * The `user_id` was created in a different environment (Sandbox vs Production). * The `user_id` was previously deleted via [/user/remove](https://plaid.com/docs/api/users/index.html.md#userremove) . ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "USER_ERROR", "error_code": "USER_NOT_FOUND", "error_message": "The User you requested cannot be found. This User does not exist or has had access removed by the user.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Errors - Virtual Accounts errors (Europe) | Plaid Docs Virtual Account(UK/EU) Errors  ============================== #### TRANSACTION\_INSUFFICIENT\_FUNDS  ##### Common Causes  * The account does not have sufficient funds to complete the transaction. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSACTION_ERROR", "error_code": "TRANSACTION_INSUFFICIENT_FUNDS", "error_message": "There are insufficient funds to complete the transaction", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSACTION\_AMOUNT\_EXCEEDED  ##### Common Causes  * The transaction amount exceeds the allowed threshold configured for this client. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSACTION_ERROR", "error_code": "TRANSACTION_AMOUNT_EXCEEDED", "error_message": "Transaction amount exceeds the allowed threshold for this client", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSACTION\_ON\_SAME\_ACCOUNT  ##### Common Causes  * The recipient bank account details on the transaction are incorrect and refer to the source Virtual Account. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSACTION_ERROR", "error_code": "TRANSACTION_ON_SAME_ACCOUNT", "error_message": "Payment to the same account is not allowed", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSACTION\_CURRENCY\_MISMATCH  ##### Common Causes  * The currency on the recipient bank account is different than that of the wallet. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSACTION_ERROR", "error_code": "TRANSACTION_CURRENCY_MISMATCH", "error_message": "The currency between the wallet and recipient account is different", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSACTION\_IBAN\_INVALID  ##### Common Causes  * The provided IBAN on the recipient bank account is invalid. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSACTION_ERROR", "error_code": "TRANSACTION_IBAN_INVALID", "error_message": "The provided IBAN is invalid", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSACTION\_BACS\_INVALID  ##### Common Causes  * The provided Account Number and/or Sort Code on the recipient account is invalid. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSACTION_ERROR", "error_code": "TRANSACTION_BACS_INVALID", "error_message": "The provided BACS account number and/or sort code is invalid", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSACTION\_FAST\_PAY\_DISABLED  ##### Common Causes  * The provided Sort Code on the recipient account is not enabled for Faster Payments. GBP transactions out of Virtual Accounts in GB are made via the Faster Payments rail. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSACTION_ERROR", "error_code": "TRANSACTION_FAST_PAY_DISABLED", "error_message": "The recipient sort code is not enabled for faster payments", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### TRANSACTION\_EXECUTION\_FAILED  ##### Common Causes  * The transaction failed to execute due to an internal error. * The transaction might have been declined by the receiving bank. * Technical issues with the payment processor. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSACTION_ERROR", "error_code": "TRANSACTION_EXECUTION_FAILED", "error_message": "There was a problem executing the transaction. Please retry.", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### NONIDENTICAL\_REQUEST  ##### Common Causes  * The request parameters have changed compared to the original request with the same idempotency key. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSACTION_ERROR", "error_code": "NONIDENTICAL_REQUEST", "error_message": "Request body does not match previous request with this idempotency key", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` #### REQUEST\_CONFLICT  ##### Common Causes  * The original request is still processing and has not completed. * A network or system issue caused a delay in processing the original request, resulting in a conflict when the new request is sent. ##### Troubleshooting steps  API error response ```json http code 400 { "error_type": "TRANSACTION_ERROR", "error_code": "REQUEST_CONFLICT", "error_message": "Original request is still processing", "display_message": null, "request_id": "HNTDNrA8F1shFEW" } ``` --- # Financial Insights | Plaid Docs Financial insights products  ============================ #### Review and compare solutions  Overview and comparison of financial insights solutions These products serve use cases such as personal finance and budgeting, loan payback and debt management, expense and accounting applications, and wealth management and investing. Note that none of these products may be used as part of a credit or underwriting decisioning process; for underwriting use cases, see [credit underwriting products](https://plaid.com/docs/underwriting/index.html.md) . #### Transactions  [Transactions](https://plaid.com/docs/transactions/index.html.md) gets transaction data for an end user's account, such as a checking, savings, or credit card account. Transaction data includes details such as date, merchant, and category; for some transactions, it will also include location data and a merchant name that has been enhanced for greater human readability. Any transaction data fields not provided to Plaid directly by the financial institution are derived via Plaid's ML-powered transactions enrichment engine. New and updated transactions are typically extracted between one and four times per day, depending on the institution. ##### Transactions Refresh  [Transactions Refresh](https://plaid.com/docs/transactions/index.html.md) is an optional add-on for Transactions that can be used to trigger an on-demand, real-time update of transactions data. Transactions Refresh provides on-demand updates only; Plaid does not offer a real-time feed of transactions updates. ##### Recurring Transactions  [Recurring Transactions](https://plaid.com/docs/transactions/index.html.md#recurring-transactions) , available in the US, CA, and UK, is an optional add-on for Transactions that can be used to identify recurring transaction streams. Recurring Transactions is typically used by financial management apps to power features such as budget analysis and helping users identify and cancel unwanted subscriptions. #### Enrich  [Enrich](https://plaid.com/docs/enrich/index.html.md) allows you to provide your own transactions data and uses the same ML-powered enrichment engine used by the Transactions product to enhance this data with more details, such as category, location, and merchant name. Unlike most other Plaid products, Enrich does not use Link to connect to an end user's financial account; Enrich is designed for customers who already have transactions data from a non-Plaid source and would like to enhance it to provide better insights to their customers. #### Liabilities  [Liabilities](https://plaid.com/docs/liabilities/index.html.md) gets details about an end user's debt, including interest rate, outstanding balance, repayment schedule, and details of the most recent repayment. Supported loan types are credit cards, private student loans, mortgages, and PayPal loans. Liabilities does not provide transaction history. For full transaction and loan details, use both Liabilities and Transactions together. #### Investments  [Investments](https://plaid.com/docs/investments/index.html.md) gets details about an end user's investment account, such as a brokerage account or 401(k). Investments comes with access to two main features: Investments Holdings, which provides details on the specific assets held, including type, description, value, cost basis, and acquisition date; and Investments Transactions, which provides details on transactions (such as trades, transfers, or dividends) within an investment account. ##### Investments Refresh  [Investments Refresh](https://plaid.com/docs/investments/index.html.md) is an optional add-on for Investments that can be used to trigger an on-demand, real-time update of investments data. #### Transactions, Investments, Liabilities, and Enrich comparison table  | | Transactions | Investments | Liabilities | Enrich | | --- | --- | --- | --- | --- | | Summary | Details on transactions | Details on investments and investments transactions | Details on loans, payments, balances, and interest | Enrich your existing transactions data | | Main supported account types | Checking, savings, credit cards | Brokerage accounts, including retirement | Credit cards, private student loans, mortgages | Checking, savings, credit cards | | Supports brokerage accounts | No | Yes | No | No | | Provides transaction details | Yes | Yes | No (only most recent payment) | N/A | | Provides ML-enhanced transaction descriptions and details | Yes | No | No | Yes | | Provides interest rates | No | No | Yes | No | | Typical update frequency | 1-4 times per day | Once per day, after market close | Once per day | N/A | | Optional Refresh add-on for on-demand updates | Yes | Yes | No | N/A | | Supported countries | US, CA, UK, Europe | US | US, CA (CA coverage limited) | US, CA | | Billing plans available | Pay-as-you-go or 12-month contract | Pay-as-you-go or 12-month contract | Pay-as-you-go or 12-month contract | Pay-as-you-go or 12-month contract | --- # Identity Verification - Managing failed verifications | Plaid Docs Operational guide  ================== #### Operational guidance for Identity Verification, including how to manage failed verifications  #### Overview  The most common reason for Identity Verification failures is bad actors and attempted fraud. However, sometimes a genuine user may fail a check due to various reasons, such as accidentally entering incorrect information, a lack of records available to confirm their identity, or issues with their identity documents. This page discusses common reasons why legitimate users may fail checks and how you can handle these issues. #### Common causes for Data Source Verification failures  ##### No match  Causes include: * Recent personal information changes, such as a change of address or a legal name change * If you are providing any user information via the API rather than Link, it must use the correct format. For example, if you send DOB as month/day/year rather than in ISO format, it will cause date of birth mismatches. See [Input validation rules](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md) . ##### No data  Causes include: * Phone number appears less consistently in data sources than other fields, and is most likely to result in "no data" * Recent immigrants and younger end users are less likely to have data on file * Countries other than the US have less complete records and are less likely to have data source matches #### Common causes for Documentary Verification failures  * Expired documents will fail Documentary Verification, even if they are genuine * Documents that do not match the name and date of birth entered will fail #### Common causes for Risk Check failures  See [Risk Checks](https://plaid.com/docs/identity-verification/risk-checks/index.html.md) for more information. #### Common causes for Selfie Check failures  Causes generally involve low-quality images, which can be caused by: * Poor quality camera, such as one found on a very old, low-end device * Insufficient lighting * Improper framing (head cut off or not facing camera) * Excessive glare from glasses * Motion blur while taking photo Plaid provides guidance in Link to help users take appropriate selfies. #### Managing failures  If you have reason to believe that the end user's information is correct, you can override a failure via the Dashboard by clicking the **Override Result** button on the verification detail page in the Dashboard. To allow a user to retry a verification, you can issue a retry. For instructions on the process, see [Retries](https://plaid.com/docs/identity-verification/index.html.md#retries) . #### Reporting issues  If at any point you believe that the Identity Verification result was incorrect, you can use the **Report a Problem** button in the Identity Verification Dashboard to inform Plaid. If you require a response, file a ticket via the Dashboard instead. --- # Identity Verification - Input validation rules | Plaid Docs Input validation rules  ======================= Plaid does as much as possible to ensure the user data you collect and verify is clean and standardized. If you are submitting data about the user via the API, you will need to match the formatting and standardization requirements described below. To help with development, we also provide a [JSON file containing the same validation rules](https://plaid.com/schema/identity_verification_api.json) . #### ID numbers  Plaid's Data Source Verification will automatically collect, validate, and verify any of the following ID numbers for countries that you've enabled in the Dashboard Editor. If you are separately collecting ID numbers outside of Link, or if you have existing customer data you're looking to import into Plaid, you can submit this data programmatically via [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) or [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . The table below lists each ID number that Identity Verification supports. The `API type` is a unique identifier that you should provide via API via the `id_number.type` field. ID Numbers submitted via API should be stripped of any formatting characters like spaces, periods, and dashes. The table below also includes the exact regular expressions we use to decide whether a given ID Number is well-formed and valid for that region's ID type. Plaid may perform additional validation to ensure the ID number is valid for the selected type. For example, the SSA will not issue SSNs with specific numbers in certain positions. SSNs that meet any of the following conditions will not be accepted: * Begin with "9", "666", or "000" * Have the number "00" in positions 4 – 5 * Have the number "0000" in positions 6 – 9 _Need this data for your code? [Download these validation rules in JSON form](https://plaid.com/schema/identity_verification_api.json)_ | Country | Country Code | ID Name | API Type | Format | | --- | --- | --- | --- | --- | | Argentina | `AR` | Documento Nacional de Identidad (DNI) | `ar_dni` | `\A\d{8,10}\z` | | Australia | `AU` | Driver's License | `au_drivers_license` | `\A[A-Z0-9]{6,11}\z` | | Australia | `AU` | Passport Number | `au_passport` | `\A[A-Z0-9]{7,9}\z` | | Brazil | `BR` | Cadastro de Pessoas Físicas (CPF) | `br_cpf` | `\A\d{11}\z` | | Canada | `CA` | Social Insurance Number (SIN) | `ca_sin` | `\A\d{9}\z` | | Chile | `CL` | Rol Único Nacional (RUN) | `cl_run` | `\A\d{7,8}[0-9Kk]\z` | | China | `CN` | Resident Identity Card Number | `cn_resident_card` | \`\\A\\d{15} | | Colombia | `CO` | Número de Identificación Tributaria (NIT) | `co_nit` | `\A\d{8,10}\z` | | Denmark | `DK` | Civil Personal Registration (CPR) | `dk_cpr` | `\A\d{9,11}\z` | | Egypt | `EG` | National ID Card Number | `eg_national_id` | `\A\d{14}\z` | | Hong Kong | `HK` | Hong Kong Identity (HKID) | `hk_hkid` | `\A[A-Z0-9]{8,9}\z` | | India | `IN` | Permanent Account Number (PAN) | `in_pan` | `\A[A-Z]{5}\d{4}[A-Z]\z` | | India | `IN` | Voter ID (EPIC) | `in_epic` | `\A[A-Z]{3}\d{7}\z` | | Italy | `IT` | Codice Fiscale (CF) | `it_cf` | `\A[A-Z]{6}\d{2}[A-Z]\d{2}[A-Z]\d{3}[A-Z]\z` | | Japan | `JP` | "My Number" Resident Record Code | `jp_my_number` | `\A\d{12}\z` | | Jordan | `JO` | Civil Identification Number | `jo_civil_id` | `\A\d{10,14}\z` | | Kenya | `KE` | Huduma Namba | `ke_huduma_namba` | `\A\d{10}\z` | | Kuwait | `KW` | Civil ID Card Number | `kw_civil_id` | `\A\d{12}\z` | | Malaysia | `MY` | National Registration Identity Card Number (NRIC) | `my_nric` | `\A\d{12}\z` | | Mexico | `MX` | Clave Única de Registro de Población (CURP) | `mx_curp` | `\A[A-Z]{4}\d{6}[A-Z]{6}[A-Z\d]\d\z` | | Mexico | `MX` | Registro Federal de Contribuyentes (RFC) | `mx_rfc` | `\A[A-Z]{4}\d{6}[A-Z\d]{3}\z` | | New Zealand | `NZ` | Driver's License | `nz_drivers_license` | `\A[A-Z]{2}\d{6}\z` | | Nigeria | `NG` | National ID Number | `ng_nin` | `\A\d{11}\z` | | Oman | `OM` | Identity Card Number | `om_civil_id` | `\A\d{8,9}\z` | | Philippines | `PH` | PhilSys Number | `ph_psn` | `\A\d{12}\z` | | Poland | `PL` | PESEL Number | `pl_pesel` | `\A\d{11}\z` | | Romania | `RO` | Cod Numeric Personal (CNP) | `ro_cnp` | `\A\d{13}\z` | | Saudi Arabia | `SA` | Biṭāgat Al-ʼaḥwāl | `sa_national_id` | `\A[A-Z0-9]{10}\z` | | Singapore | `SG` | National Registration Identity Card | `sg_nric` | `\A[A-Z]\d{7}[A-Z]\z` | | South Africa | `ZA` | Smart ID Card Number | `za_smart_id` | `\A\d{13}\z` | | Spain | `ES` | Documento Nacional de Identidad (DNI) | `es_dni` | `\A\d{8}[A-Z]\z` | | Spain | `ES` | Número de Identidad de Extranjero (NIE) | `es_nie` | `\A[A-Z]\d{7}[A-Z]\z` | | Sweden | `SE` | Personnummer (PIN) | `se_pin` | `\A\d{9,12}\z` | | Turkey | `TR` | T.C. Kimlik No. | `tr_tc_kimlik` | `\A\d{11}\z` | | United States | `US` | Social Security Number (SSN or ITIN) | `us_ssn` | `\A\d{9}\z` | | United States | `US` | Social Security Number (SSN or ITIN) Last 4 | `us_ssn_last_4` | `\A\d{4}\z` | #### Input validation by country  Address standards vary by country. Some countries do not support postal code or region (the equivalent of "state" or "province" depending on the region). In other countries, postal code and/or region is valid in a sense, but superfluous and not typically collected in native forms. Separately, variations in identity data coverage mean that collection of "ID Number" is a required part of Data Source Verification in some countries, optional (configured in the Dashboard Editor) for other countries, and not supported in countries that do not support Data Source Verification at all. This regional variation is reflected in the table below. The labels for each input field below correspond to the following input validations: * `address.postal_code` and `address.region` * **Required** - If `address` is provided as part of the request, this field must always be present. For a set of accepted `region` codes, see [country subdivision codes in JSON form](https://plaid.com/documents/country_subdivision_codes.json) . If a country is absent from this list, it means that `address.region` is not accepted for that country. * **Not Accepted** - If `address` is provided as part of the request, this field must be omitted. Specifically, the key should be omitted from the `address` object (as opposed to the key being present with a null value) For the `region` field, Identity Verification accepts a subset of ISO 3166-2 subdivision codes, excluding subdivision codes that are not typically used in addresses (these exclusions primarily impact Italy and Hong Kong). For a full list of accepted codes, see [country subdivision codes in JSON form](https://plaid.com/documents/country_subdivision_codes.json) . Only the portion of the region code after the hyphen should be sent, since the country code can be extrapolated from the `country` field. For example, for Rome, use `country: "IT", region: "RM"`. * `id_number` * **Required** - If `id_number` is not provided for this country, `kyc_check` will treat the Identity Verification Session as having incomplete data and will require user interaction with the Identity Verification modal in order to collect `id_number` * **Optional** - If `id_number` is not provided for this country **and** your Identity Verification Template is configured to not collect ID numbers for this country then Identity Verification will automatically run the `kyc_check` step without any user interaction as long as all other required input fields are provided. Similar to the address fields, the API requires you omit the `id_number` key entirely if you are not providing ID number data * **Not Accepted** - ID number verification is not supported for this country and the `id_number` field should always be omitted from API requests _Need this data for your code? [Download these validation rules in JSON form](https://plaid.com/schema/identity_verification_api.json)_ | Country | Country Code | `address.postal_code` | `address.region` | `id_number` | | --- | --- | --- | --- | --- | | Afghanistan | `AF` | Required | Not Accepted | Not Accepted | | Albania | `AL` | Required | Not Accepted | Not Accepted | | Algeria | `DZ` | Required | Not Accepted | Not Accepted | | Andorra | `AD` | Required | Not Accepted | Not Accepted | | Angola | `AO` | Not Accepted | Not Accepted | Not Accepted | | Anguilla | `AI` | Not Accepted | Not Accepted | Not Accepted | | Antigua & Barbuda | `AG` | Not Accepted | Not Accepted | Not Accepted | | Argentina | `AR` | Required | Required | Required | | Armenia | `AM` | Required | Not Accepted | Not Accepted | | Aruba | `AW` | Not Accepted | Not Accepted | Not Accepted | | Australia | `AU` | Required | Required | Required | | Austria | `AT` | Required | Not Accepted | Not Accepted | | Azerbaijan | `AZ` | Required | Not Accepted | Not Accepted | | Bahamas | `BS` | Not Accepted | Not Accepted | Not Accepted | | Bahrain | `BH` | Required | Not Accepted | Not Accepted | | Bangladesh | `BD` | Required | Not Accepted | Not Accepted | | Barbados | `BB` | Required | Not Accepted | Not Accepted | | Belarus | `BY` | Required | Not Accepted | Not Accepted | | Belgium | `BE` | Required | Not Accepted | Not Accepted | | Belize | `BZ` | Not Accepted | Not Accepted | Not Accepted | | Benin | `BJ` | Not Accepted | Not Accepted | Not Accepted | | Bermuda | `BM` | Required | Not Accepted | Not Accepted | | Bhutan | `BT` | Required | Not Accepted | Not Accepted | | Bolivia | `BO` | Not Accepted | Not Accepted | Not Accepted | | Bosnia & Herzegovina | `BA` | Required | Not Accepted | Not Accepted | | Botswana | `BW` | Required | Not Accepted | Not Accepted | | Brazil | `BR` | Required | Required | Required | | British Virgin Islands | `VG` | Required | Not Accepted | Not Accepted | | Brunei | `BN` | Required | Not Accepted | Not Accepted | | Bulgaria | `BG` | Required | Not Accepted | Not Accepted | | Burkina Faso | `BF` | Not Accepted | Not Accepted | Not Accepted | | Burundi | `BI` | Required | Not Accepted | Not Accepted | | Cambodia | `KH` | Required | Not Accepted | Not Accepted | | Cameroon | `CM` | Required | Not Accepted | Not Accepted | | Canada | `CA` | Required | Required | Optional | | Cape Verde | `CV` | Required | Not Accepted | Not Accepted | | Caribbean Netherlands | `BQ` | Required | Not Accepted | Not Accepted | | Cayman Islands | `KY` | Required | Not Accepted | Not Accepted | | Central African Republic | `CF` | Required | Not Accepted | Not Accepted | | Chad | `TD` | Not Accepted | Not Accepted | Not Accepted | | Chile | `CL` | Required | Required | Required | | China | `CN` | Required | Required | Required | | Colombia | `CO` | Required | Required | Required | | Comoros | `KM` | Required | Not Accepted | Not Accepted | | Congo - Brazzaville | `CG` | Required | Not Accepted | Not Accepted | | Cook Islands | `CK` | Required | Not Accepted | Not Accepted | | Costa Rica | `CR` | Required | Not Accepted | Not Accepted | | Croatia | `HR` | Required | Not Accepted | Not Accepted | | Curaçao | `CW` | Not Accepted | Not Accepted | Not Accepted | | Cyprus | `CY` | Required | Not Accepted | Not Accepted | | Czech Republic | `CZ` | Required | Not Accepted | Required | | Côte d'Ivoire | `CI` | Required | Not Accepted | Not Accepted | | Denmark | `DK` | Required | Not Accepted | Required | | Djibouti | `DJ` | Not Accepted | Not Accepted | Not Accepted | | Dominica | `DM` | Required | Not Accepted | Not Accepted | | Dominican Republic | `DO` | Required | Not Accepted | Not Accepted | | Ecuador | `EC` | Required | Not Accepted | Not Accepted | | Egypt | `EG` | Required | Required | Not Accepted | | El Salvador | `SV` | Required | Not Accepted | Not Accepted | | Eritrea | `ER` | Required | Not Accepted | Not Accepted | | Estonia | `EE` | Required | Not Accepted | Not Accepted | | Eswatini | `SZ` | Required | Not Accepted | Not Accepted | | Ethiopia | `ET` | Required | Not Accepted | Not Accepted | | Faroe Islands | `FO` | Required | Not Accepted | Not Accepted | | Fiji | `FJ` | Not Accepted | Not Accepted | Not Accepted | | Finland | `FI` | Required | Not Accepted | Required | | France | `FR` | Required | Not Accepted | Not Accepted | | French Polynesia | `PF` | Required | Not Accepted | Not Accepted | | Gabon | `GA` | Required | Not Accepted | Not Accepted | | Gambia | `GM` | Required | Not Accepted | Not Accepted | | Georgia | `GE` | Required | Not Accepted | Not Accepted | | Germany | `DE` | Required | Not Accepted | Not Accepted | | Ghana | `GH` | Not Accepted | Not Accepted | Not Accepted | | Gibraltar | `GI` | Required | Not Accepted | Not Accepted | | Greece | `GR` | Required | Not Accepted | Not Accepted | | Greenland | `GL` | Required | Not Accepted | Not Accepted | | Grenada | `GD` | Required | Not Accepted | Not Accepted | | Guatemala | `GT` | Required | Required | Not Accepted | | Guernsey | `GG` | Required | Not Accepted | Not Accepted | | Guinea | `GN` | Required | Not Accepted | Not Accepted | | Guinea-Bissau | `GW` | Required | Not Accepted | Not Accepted | | Guyana | `GY` | Required | Not Accepted | Not Accepted | | Haiti | `HT` | Required | Not Accepted | Not Accepted | | Honduras | `HN` | Required | Not Accepted | Not Accepted | | Hong Kong | `HK` | Not Accepted | Required | Required | | Hungary | `HU` | Required | Not Accepted | Not Accepted | | Iceland | `IS` | Required | Not Accepted | Not Accepted | | India | `IN` | Required | Required | Required | | Indonesia | `ID` | Required | Required | Not Accepted | | Iraq | `IQ` | Required | Not Accepted | Not Accepted | | Ireland | `IE` | Required | Required | Not Accepted | | Isle of Man | `IM` | Required | Not Accepted | Not Accepted | | Israel | `IL` | Required | Not Accepted | Not Accepted | | Italy | `IT` | Required | Required | Optional | | Jamaica | `JM` | Not Accepted | Not Accepted | Not Accepted | | Japan | `JP` | Required | Required | Optional | | Jersey | `JE` | Required | Not Accepted | Not Accepted | | Jordan | `JO` | Required | Not Accepted | Not Accepted | | Kazakhstan | `KZ` | Required | Not Accepted | Not Accepted | | Kenya | `KE` | Required | Not Accepted | Required | | Kiribati | `KI` | Required | Not Accepted | Not Accepted | | Kosovo | `XK` | Required | Not Accepted | Not Accepted | | Kuwait | `KW` | Required | Not Accepted | Not Accepted | | Kyrgyzstan | `KG` | Required | Not Accepted | Not Accepted | | Laos | `LA` | Required | Not Accepted | Not Accepted | | Latvia | `LV` | Required | Not Accepted | Not Accepted | | Lebanon | `LB` | Required | Not Accepted | Not Accepted | | Lesotho | `LS` | Required | Not Accepted | Not Accepted | | Liberia | `LR` | Required | Not Accepted | Not Accepted | | Liechtenstein | `LI` | Required | Not Accepted | Not Accepted | | Lithuania | `LT` | Required | Not Accepted | Not Accepted | | Luxembourg | `LU` | Required | Not Accepted | Not Accepted | | Macao SAR China | `MO` | Required | Not Accepted | Not Accepted | | Madagascar | `MG` | Required | Not Accepted | Not Accepted | | Malawi | `MW` | Not Accepted | Not Accepted | Not Accepted | | Malaysia | `MY` | Required | Required | Required | | Maldives | `MV` | Required | Not Accepted | Not Accepted | | Mali | `ML` | Not Accepted | Not Accepted | Not Accepted | | Malta | `MT` | Required | Not Accepted | Not Accepted | | Mauritania | `MR` | Required | Not Accepted | Not Accepted | | Mauritius | `MU` | Required | Not Accepted | Not Accepted | | Mexico | `MX` | Required | Required | Required | | Moldova | `MD` | Required | Not Accepted | Not Accepted | | Monaco | `MC` | Required | Not Accepted | Not Accepted | | Mongolia | `MN` | Required | Not Accepted | Not Accepted | | Montenegro | `ME` | Required | Not Accepted | Not Accepted | | Montserrat | `MS` | Required | Not Accepted | Not Accepted | | Morocco | `MA` | Required | Not Accepted | Not Accepted | | Mozambique | `MZ` | Required | Not Accepted | Not Accepted | | Myanmar (Burma) | `MM` | Required | Not Accepted | Not Accepted | | Namibia | `NA` | Required | Not Accepted | Not Accepted | | Nauru | `NR` | Required | Not Accepted | Not Accepted | | Nepal | `NP` | Required | Not Accepted | Not Accepted | | Netherlands | `NL` | Required | Not Accepted | Not Accepted | | New Zealand | `NZ` | Required | Required | Optional | | Nicaragua | `NI` | Required | Not Accepted | Not Accepted | | Niger | `NE` | Required | Not Accepted | Not Accepted | | Nigeria | `NG` | Required | Required | Required | | Niue | `NU` | Required | Not Accepted | Not Accepted | | North Macedonia | `MK` | Required | Not Accepted | Not Accepted | | Norway | `NO` | Required | Not Accepted | Not Accepted | | Oman | `OM` | Required | Not Accepted | Not Accepted | | Pakistan | `PK` | Required | Not Accepted | Not Accepted | | Palestinian Territories | `PS` | Required | Not Accepted | Not Accepted | | Panama | `PA` | Not Accepted | Required | Not Accepted | | Papua New Guinea | `PG` | Required | Not Accepted | Not Accepted | | Paraguay | `PY` | Required | Not Accepted | Not Accepted | | Peru | `PE` | Required | Required | Not Accepted | | Philippines | `PH` | Required | Required | Optional | | Poland | `PL` | Required | Not Accepted | Optional | | Portugal | `PT` | Required | Required | Not Accepted | | Qatar | `QA` | Not Accepted | Not Accepted | Not Accepted | | Romania | `RO` | Required | Required | Not Accepted | | Russia | `RU` | Required | Required | Not Accepted | | Rwanda | `RW` | Required | Not Accepted | Not Accepted | | Samoa | `WS` | Required | Not Accepted | Not Accepted | | San Marino | `SM` | Required | Not Accepted | Not Accepted | | Saudi Arabia | `SA` | Required | Not Accepted | Not Accepted | | Senegal | `SN` | Required | Not Accepted | Not Accepted | | Serbia | `RS` | Required | Not Accepted | Not Accepted | | Seychelles | `SC` | Required | Not Accepted | Not Accepted | | Sierra Leone | `SL` | Not Accepted | Not Accepted | Not Accepted | | Singapore | `SG` | Required | Not Accepted | Required | | Slovakia | `SK` | Required | Not Accepted | Not Accepted | | Slovenia | `SI` | Required | Not Accepted | Not Accepted | | Solomon Islands | `SB` | Required | Not Accepted | Not Accepted | | Somalia | `SO` | Required | Not Accepted | Not Accepted | | South Africa | `ZA` | Required | Required | Required | | South Korea | `KR` | Required | Required | Not Accepted | | South Sudan | `SS` | Not Accepted | Not Accepted | Not Accepted | | Spain | `ES` | Required | Required | Optional | | Sri Lanka | `LK` | Required | Not Accepted | Not Accepted | | St. Kitts & Nevis | `KN` | Required | Not Accepted | Not Accepted | | St. Lucia | `LC` | Required | Not Accepted | Not Accepted | | St. Martin | `MF` | Required | Not Accepted | Not Accepted | | St. Vincent & Grenadines | `VC` | Required | Not Accepted | Not Accepted | | Sudan | `SD` | Required | Not Accepted | Not Accepted | | Suriname | `SR` | Required | Not Accepted | Not Accepted | | Sweden | `SE` | Required | Not Accepted | Required | | Switzerland | `CH` | Required | Not Accepted | Not Accepted | | São Tomé & Príncipe | `ST` | Required | Not Accepted | Not Accepted | | Taiwan | `TW` | Required | Not Accepted | Not Accepted | | Tajikistan | `TJ` | Required | Not Accepted | Not Accepted | | Tanzania | `TZ` | Required | Not Accepted | Not Accepted | | Thailand | `TH` | Required | Required | Not Accepted | | Timor-Leste | `TL` | Required | Not Accepted | Not Accepted | | Togo | `TG` | Not Accepted | Not Accepted | Not Accepted | | Tonga | `TO` | Not Accepted | Not Accepted | Not Accepted | | Trinidad & Tobago | `TT` | Not Accepted | Not Accepted | Not Accepted | | Tunisia | `TN` | Required | Not Accepted | Not Accepted | | Turkey | `TR` | Required | Not Accepted | Required | | Turkmenistan | `TM` | Required | Not Accepted | Not Accepted | | Turks & Caicos Islands | `TC` | Required | Not Accepted | Not Accepted | | Tuvalu | `TV` | Not Accepted | Not Accepted | Not Accepted | | Uganda | `UG` | Not Accepted | Not Accepted | Not Accepted | | Ukraine | `UA` | Required | Not Accepted | Not Accepted | | United Arab Emirates | `AE` | Not Accepted | Required | Not Accepted | | United Kingdom | `GB` | Required | Not Accepted | Not Accepted | | United States | `US` | Required | Required | Optional | | Uruguay | `UY` | Required | Not Accepted | Not Accepted | | Uzbekistan | `UZ` | Required | Not Accepted | Not Accepted | | Vanuatu | `VU` | Not Accepted | Not Accepted | Not Accepted | | Vatican City | `VA` | Required | Not Accepted | Not Accepted | | Venezuela | `VE` | Required | Not Accepted | Not Accepted | | Vietnam | `VN` | Required | Not Accepted | Not Accepted | | Western Sahara | `EH` | Required | Not Accepted | Not Accepted | | Yemen | `YE` | Not Accepted | Not Accepted | Not Accepted | | Zambia | `ZM` | Required | Not Accepted | Not Accepted | | Zimbabwe | `ZW` | Not Accepted | Not Accepted | Not Accepted | --- # Identity Verification - Introduction to Identity Verification | Plaid Docs Introduction to Identity Verification   ======================================= #### Verify the identity of your users for global KYC and anti-fraud  Get started with Identity Verification [API Reference](https://plaid.com/docs/api/products/identity-verification/index.html.md) [Request Access](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) [Quickstart](https://github.com/plaid/idv-quickstart) [Demo](https://plaid.coastdemo.com/share/68a50b5fc54642a282e49c0e?zoom=100) #### Overview  Plaid Identity Verification (IDV) lets you verify the identity of your customers and seamlessly stitches together verification methods. Using Identity Verification, you can verify identification documents, phone numbers, name, date of birth, ID numbers, addresses, and more. Identity Verification also integrates directly with [Monitor](https://plaid.com/docs/monitor/index.html.md) for an end-to-end verification and KYC solution, allowing you to check for the presence of a user on watchlists and PEP lists, in addition to verifying identity. The user starts the Identity Verification process... (An image of "The user starts the Identity Verification process...") (An image of "...selects their country from a configurable list...") (An image of "...enters their phone number...") (An image of "...and, if you've enabled SMS-verification, verifies it.") (An image of "They provide their full name...") (An image of "...address...") (An image of "...date of birth...") (An image of "...and, if you've enabled Data Source Verification, an ID number.") (An image of "With Document Verification enabled, they pick a document from a configurable list...") (An image of "...and photograph the front...") (An image of "...and the back.") (An image of "With Selfie Check enabled, the user grants camera access...") (An image of "...takes a selfie...") (An image of "...decides whether to save their profile with Plaid...") (An image of "...and the flow is done.") Plaid Identity Verification can also be used together with [Plaid Identity](https://plaid.com/docs/identity/index.html.md) in a single workflow to provide full identity verification and fraud reduction. Identity Verification is used to verify that the user of your app is the person they claim to be, while [Identity](https://plaid.com/docs/identity/index.html.md) is used to confirm that the ownership information on their linked bank or credit card account matches this verified identity. Identity Verification can be used to verify end users in nearly 190 countries. To integrate with Identity Verification, your company must be based in the US, Canada, or UK. [Watch video](https://www.youtube.com/watch?v=WyADMPl1R8w) #### Identity Verification checks  Plaid offers a variety of verification checks to choose from. You can combine multiple verification checks within a single Identity Verification template via the Workflow Management editor, and even run certain checks conditionally, such as only running a particular verification if another verification fails or indicates a high-risk session, or running different checks based on your user's country of origin. After running your selected checks, Identity Verification will also display a set of granular risk assessments (email risk, phone risk, etc.) in the Dashboard for each session, along with an overall risk score, helping you to understand which factors contributed to the session passing or failing and which sessions have been identified as the highest risk. When configuring your checks, it is typically recommended to start with the default templates and risk rules, then fine-tune them as needed based on your results. ##### SMS Verification  SMS Verification verifies a user's phone number by asking them to enter a code sent via SMS. ##### Data Source Verification  Data Source Verification (formerly known as Lightning Verification) verifies a user's name, address, date of birth, phone number, and ID number (such as SSN) against available records. These records are sourced from high-quality, trusted databases such as voter and driver registration records, property records, and credit bureau records. You can configure the level of matching required for each field in your template's Identity Rules. The results of this check will be summarized in the `kyc_check` object in the API. Note that certain end user segments, such as recent immigrants and end users aged 18-21, are less likely to pass data source verification, due to having a "thin file" (i.e., fewer data source records available to verify against). If these groups constitute a substantial portion of the audience you will be verifying, you may wish to enable Document Verification as a backup verification method. ##### Document Verification  Document Verification prompts the user to upload an image of an identity document. Plaid will use anti-fraud checks to verify that the document appears to be legitimate and is unexpired. Plaid will also verify the date of birth and name on the document against the data provided by the user (other fields that may be present on the document, such as address or national ID number, will not be verified). Plaid supports a wide range of documents; you can review and configure which document types are supported for each country. You can also require certain classes of document types, e.g. only photo IDs. If the user is on a non-mobile device, Plaid will display a QR code that they can use to perform Document Verification on mobile. They will resume the computer-based flow once the Document Verification upload is complete. This handoff process is automatic and does not require any integration work on your part. Document Verification can be used as a potential fallback for Data Source Verification (e.g. for verifying thin file customers) or as a step-up method of verification for customers with a lower [Trust Index Score](https://plaid.com/docs/identity-verification/index.html.md#trust-index-scores-us-only) . It can also be used as a primary method of verification, especially in countries where Data Source Verification is not supported. ##### AAMVA Check (beta, US only)  AAMVA (American Association of Motor Vehicle Administrators) checks can optionally be enabled as part of Document Verification. When enabled, if the end user uploads an image of a drivers license from a [participating US state](https://www.aamva.org/it-systems-participation-map?id=594) , Identity Verification will compare the text on the uploaded drivers license with the AAMVA's records. Fields compared include name, gender, height, eye color, address, date of birth, and drivers license number. ##### Selfie Check  When Selfie Check is enabled, the user will be asked to take a selfie on their mobile device as part of the verification process. Plaid will verify that the selfie submitted is a genuine, live video of a real human. If Document Verification is enabled, Selfie Check will also verify that the selfie matches the photo in the document. If the user is on a non-mobile device, Plaid will display a QR code that they can use to perform the Selfie Check on mobile. They will resume the computer-based flow once the Selfie Check is complete. This handoff process is automatic and does not require any integration work on your part. After the end user has passed a Selfie Check, you can [issue additional on-demand liveness checks](https://plaid.com/docs/identity-verification/index.html.md#retries) at any time as a form of step-up verification. These checks will check both for liveness and for a match to the previous Selfie Check. ##### Age verification  If both Selfie Checks and Document Verification are enabled, an age verification check will automatically be run. Identity Verification will check that the user's photos appear consistent with the date of birth the user has provided. ##### AML Screening  If you're also using [Monitor](https://plaid.com/docs/monitor/index.html.md) , AML Screening allows you to screen a user against government watchlists during an IDV session by incorporating one of your Monitor screening programs into an IDV template. ##### Address requirements  Within the workflow configuration, you can set a number of address requirements. You can optionally require that the user provide a residential address and/or a physical address (i.e., block PO box addresses). You can also require that any ID documents presented in the Document Verification check are issued by the same country as the country in the user's address. ##### Risk Check  Plaid automatically runs anti-fraud checks in the background of a user's verification session and summarizes the results into several categories. The data collected in each category is analyzed and assigned a risk level. Whether the overall risk check passes or fails is determined by the template's Risk Rules, which you can configure. For more details on the risk check process and what each check represents, see [Risk checks](https://plaid.com/docs/identity-verification/risk-checks/index.html.md) . ##### Trust Index Scores (US only)  For verifications of US users, Identity Verification will calculate a Trust Index Score, which provides an overall holistic risk assessment based on the Risk Check results. Via the Dashboard, you can view the primary drivers of the Trust Index Score for any given verification. You can also configure a minimum Trust Index Threshold in addition to your template's Risk Rules. The Dashboard will display several recommended thresholds, as well as what percentage of your traffic would be blocked at each score threshold, once you have enough traffic assessed. You can also configure conditional step-up verifications based on the Trust Index Score. For example, you can allow users with a high Trust Index Score to bypass documentary verification, while requiring for users with a lower score. ##### Checks not performed by Identity Verification  Identity Verification is not a background check tool; it will not report whether an end user has a criminal record. Identity Verification does not check citizenship, immigration status, or residency status, although you may be able to build your own business logic to determine this supported by Identity Verification results. For example, a valid passport from a country will typically indicate that the end user is a citizen of that country. Identity Verification does not check for duplicate user submissions based on identity data such as phone number or national ID number (although multiple submissions from the same device, or multiple submissions using different names but the same ostensibly unique PII such as phone number, are tracked and will increase the risk score). Instead, it checks for duplicates using the `client_user_id` provided when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see [Client user ID](https://plaid.com/docs/identity-verification/index.html.md#client-user-id) . Per Plaid's [terms and policies](https://plaid.com/legal/) , Identity Verification is not intended to be used by end users under the age of 18. #### Identity Verification integration process  [Watch video](https://www.youtube.com/watch?v=5EZwC5w6KCw) Identity Verification is not available by default in the Sandbox environment. To obtain Sandbox access, [request full Production access for Identity Verification](https://dashboard.plaid.com/settings/team/products) , which will automatically grant Sandbox access, or, if you are not ready for Production access, [contact sales](https://plaid.com/products/identity-verification/#contact-form) . To obtain Sandbox access for Identity Verification if you are already using another Plaid product, you can also contact your account manager or submit an [access request ticket](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) . The steps below explain how to set up the standard Identity Verification flow. For details on other flow options, including the backend-only flow and hosted UI flow, see [Integration options for Identity Verification](https://plaid.com/docs/identity-verification/index.html.md#integration-options-for-identity-verification) . Note that unlike other Plaid products, which are configured primarily via the API, most options for Identity Verification are configured on the web, via the [Template Editor](https://dashboard.plaid.com/identity_verification/templates) within the Identity Verification Dashboard. Detailed documentation on configuring Identity Verification templates is available via in-app help within the Template Editor. To request access to the Template Editor and Identity Verification Dashboard, contact your Plaid account manager, or file a [Product Access request](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . 1. Visit the [Plaid Dashboard](https://dashboard.plaid.com/) and select **Identity Verification** from the left sidebar. If you don't see this option, you may need to talk to your Plaid account manager and ask them to enable this product for you, or file a [Product access request](https://dashboard.plaid.com/support/new/product-and-development/product-troubleshooting/request-product-access) . 2. Select or create the template you want to use, click the **Integration** button, and copy the `template_id`. * (Optional) If you plan to integrate with [Monitor](https://plaid.com/docs/monitor/index.html.md) , make sure to enable the **AML Screening** option and select the appropriate Monitor program within the IDV template editor. 3. (Optional) Call [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) if you already have information about your user that you can fill out on their behalf. See [pre-populating user information](https://plaid.com/docs/identity-verification/index.html.md#streamlining-link-by-pre-populating-user-information-hybrid-link-flow) for more details. 4. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following: * For `identity_verification.template_id`, use the `template_id` you copied in step 2. * For `products`, use `["identity_verification"]`. Identity Verification is mutually exclusive with other products. * Provide `user.client_user_id` and optionally `user.email_address`. See below for details on these fields. 5. On your web or mobile client, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . 6. When the user has successfully completed the client-side Link flow, you will receive an [onSuccess](https://plaid.com/docs/link/web/index.html.md#onsuccess) callback and be able to review the session in the Dashboard. The `onSuccess` callback will return a Link session ID that can be used as the `identity_verification_id` in the next step. Note that `onSuccess` does _not_ indicate that the user has passed the Identity Verification checks, but simply that they have submitted all the information requested in the Link flow. Unlike some other Plaid products, Identity Verification will not return a public token in `onSuccess`. 7. To retrieve the status of your user's verification attempt, make a call to [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) , passing in the verification session ID. You can retrieve this session ID from the metadata in the Link callbacks, from the [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) response, or from the [Identity Verification webhooks](https://plaid.com/docs/identity-verification/webhooks/index.html.md) that Plaid sends during the process. 8. You can retrieve a list of all of your user's verification attempts by making a call to [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) , passing in the `client_user_id` and the `template_id`. ##### Events and callbacks  You can optionally track the progress of users through the Link flow via client-side callbacks and events. For more information, see [Link callbacks](https://plaid.com/docs/identity-verification/link/index.html.md) . ##### Mobile support  Identity Verification is fully supported by Plaid's mobile SDKs. Because the end user may need to use the camera during the Identity Verification flow, your app must request certain permissions in order to fully support Identity Verification flows on mobile. For more details, see the documentation for the [Android](https://plaid.com/docs/link/android/index.html.md#enable-camera-support-identity-verification-only) and [iOS](https://plaid.com/docs/link/ios/index.html.md#camera-support-identity-verification-only) SDKs. ##### Client User Id  The mandatory `client_user_id` field should be a unique and persistent identifier for your customer, such as the `id` field on your users table. Identity Verification intelligently handles sessions being started with the same `client_user_id` multiple times. If your customer starts a Link session, closes it, reopens it, and reopens your Link integration, their session will resume from where they left off. Likewise, if your customer has completed their Link session in the past (by either failing verification or passing), Plaid will not serve them another session unless you've manually authorized another attempt from the Dashboard or made a call to [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) . Plaid indexes the `client_user_id` you provide, allowing you to look up users using your internal id. If you do not want to expose your internal id to Plaid directly, you can symmetrically encrypt the identifier with a secret key that only your servers know. ##### Supplementing with email  During [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) or [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) , Identity Verification accepts `email_address` as an optional additional parameter. While the field is optional, we highly recommend providing it. Identity Verification will include the user's email in the Link session and perform a number of anti-fraud related checks, including analyzing social networks, abusive emails, and email address trustworthiness. #### Integration options for Identity Verification  Identity Verification offers several options for streamlined flows. The Plaid Link flow is designed to collect high quality user data, through an optimized UI and input validation. If you are bypassing the Link data entry UI and are instead passing user data via API, be sure you are providing data in the correct format expected by the API and have taken steps to avoid issues such as typos or incorrect data entry (e.g. an end user entering a date of birth using a different date format than your app expects). Providing unvalidated or malformatted data via the API will result in degraded success rates for Data Source Verification. For more details on data formatting requirements and validation rules you can use for input you collect, see [input validation](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md) . ##### Streamlining Link by pre-populating user information (hybrid Link flow)  If you already know some information about your user (such as their name, phone number, or address), you can simplify the verification process by making a call to [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) , passing in any information you know about your user, including their `client_user_id`. When you open up a Link session against this same `client_user_id`, Identity Verification can make use of the information that you passed in. Any fields or screens requesting information you already provided will be skipped (not shown) in the UI. This means that an end user will not be able to override or change pre-populated user information during the Link flow. For data format specifications, see [Input Validation](https://plaid.com/docs/identity-verification/hybrid-input-validation/index.html.md) . ##### Data Source Checks without UI (backend flow)  If you have already obtained a user's information and their consent to share it with Plaid, and do not need interactive capabilities such as Document Check, Selfie Check, or SMS verification, you can bypass the Identity Verification UI entirely and run an entirely programmatic verification: 1. Create a template that requires only Data Source (KYC) check and does not use SMS verification. 2. Call [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) with all the user data required by this template and `gave_consent: true`. 3. Wait for the `STATUS_UPDATED` webhook to fire for the `id` returned by [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) . Alternatively, you can poll [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) with this id until the `status` is no longer `active`. 4. Call [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) with the id returned by [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) to retrieve the status of the verification. When using the backend-only flow, the Network Risk, Device and IP Address, and Behavioral Analytics checks will be unavailable, as they require client-side input. ##### Verification links (hosted flow)  Identity Verification offers the option to generate Plaid-hosted verification links. These links can be used in scenarios where your user signed up for your service outside of an app or website -- for example if a user is opening a bank account or applying for a loan in person at a brick-and-mortar retail location. To generate a verification link, click **Create verification** from the Identity Verification template view in the Dashboard. Alternatively, you can call [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) with `is_shareable: true`; a verification link will be returned in the `shareable_url` field of the response. Once you have shared the verification link, the user can open the link and complete the verification on their phone or other device. Unlike Plaid [Hosted Links](https://plaid.com/docs/link/hosted-link/index.html.md) , Identity Verification links do not expire. Note that verification links are intended to be sent directly to your users; hosting verification links via iframe will be blocked. ##### Auto-fill  When auto-fill is enabled, Plaid will use the user's phone number and date of birth to attempt to auto-fill other fields. The user will be asked to confirm their auto-filled information is accurate before submitting. Auto-fill can only be enabled when using SMS Verification and Data Source Verification and is only available for US verifications. Enabling auto-fill when possible is strongly recommended, as it has a substantial positive impact on Link flow conversion. When auto-fill is enabled, full SSN collection cannot be guaranteed; in some cases, 4 digits of the SSN may be returned, even if you have enabled collecting the 9 digit SSN. If it is critical that you collect the end user's full SSN within the Identity Verification flow, you should not enable auto-fill. Note that auto-fill is not the same as the Plaid [Returning User Experience](https://plaid.com/docs/link/returning-user/index.html.md) . The Returning User Experience is an automatic experience within Link, based on the end user's saved profile that they created during a previous Link session, while auto-fill is a configurable setting and uses Data Source Verification records for auto-filling data. ##### Hiding verification outcome  You can customize many aspects of the Identity Verification flow, including the final pane shown to the end user. If you have a more complex user risk evaluation model that uses Identity Verification as one of multiple inputs, you should select the option in the Workflow pane to "Remove Final Status Screen", preventing the user from seeing a result that may not reflect the true outcome of your verification process. ##### Overrides  If you believe the result of an Identity Verification step was incorrect, you can manually override the result via the Dashboard by clicking the **Override result** button next to the specific step on the verification detail page. It is not possible to override a result via the API. Only the result of failed steps can be overridden; you cannot override the result of a step that has passed verification. You cannot override the result of the session as a whole, but overriding a step's result will cause the verification logic to be re-evaluated for that session, which may cause the session to pass. ##### Retries  If you want to give a user another attempt to verify their identity -- for example, if they failed verification due to a typo -- you can issue them a retry. This can be done from the Dashboard when reviewing a verification by clicking **Actions > Request retry from this user** and selecting the steps to include, or via API by calling [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) with their `client_user_id`, `template_id`, and the `strategy` you want to use. Retries can be issued from any verification check. Any steps included in the retry will be reset and cleared of any PII entered by the user or passed via API in previous verification attempts. Data Source data can be passed programmatically for a retry by calling [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) and passing the user's data in the `user` object. [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) should only be used to create an initial session for users who have never been verified before. Each retry will generate a new `session_id`, with the same `client_user_id` and `template_id` used in the original session. Retries will use the most recent version of the template, which may be different from the version used in the original verification session. Retries are billed at the same rate as regular sessions. While allowing retries is useful to help users who have legitimately made an error, allowing too many retry attempts can attract fraud. We recommend starting with no more than two retry attempts allowed per user. You can also issue retries for successful verifications. In addition to retrying steps, successful verifications allow you to issue a liveness retry, which prompts the user to take a new selfie and both tests it for liveness and compares it against their previous selfie. To use this approach, select **Actions > Request retry from this user > Authenticate User > Start Re-authentication** or call [/identity\_verification/retry](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationretry) with `steps.liveness: true`. ###### Step-up verification  Retries can also be used as part of a "step-up" verification process. To use retries in this way, send the user through Identity Verification, and examine the results via the Dashboard or [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) . If their risk results meet your criteria for requiring a step-up, you can issue a retry using a different `template_id`. For example, you might send users through a template that doesn't require documentary verification, but if their risk check failed, you might step them up to a new template that does require documentary verification. ##### Financial Account Matching  If you are a customer of [Identity](https://plaid.com/docs/identity/index.html.md) or [Assets](https://plaid.com/docs/assets/index.html.md) , you can seamlessly compare a user's financial accounts with their Identity Verification profile. When a user verifies their identity and links their accounts with Plaid, we detect if they are linking a bank account that belongs to them. In the Plaid Dashboard, you'll see "match" scores against the account owner's name, email, phone number, and address. To turn on this feature, you will need to enable it in the template editor and call [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) , [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , or [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) with the same `client_user_id` that was used for Identity Verification. Financial Account Matching will only run if the `client_user_id` is associated with a successful (passed) Identity Verification session. ##### Fraud labeling  Identity Verification offers the ability to flag a session as fraudulent via the Dashboard, using the **Mark as fraud** or **Mark as not fraud** buttons. Labeling fraudulent sessions will allow Identity Verification to refine its fraud model, resulting in higher fraud detection accuracy for your integration. If necessary, you can also perform a one-time bulk upload of fraud labels; contact your account manager for more details. Fraud labeling a session does not change its pass/fail outcome. #### Supported languages  Identity Verification currently supports flows in English, French, Spanish, Japanese, and Portuguese. Link will attempt to auto-detect the correct language based on the user's browser settings. Users can also manually change the language of their session through a dropdown in the Link UI. Unlike other Plaid products, Identity Verification does not use the language setting in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . #### Supported countries  Identity Verification supports end users in all countries, with the exception of North Korea, Libya, DR Congo, Iran, Cuba, and Syria. Data Source checks are available in the following countries: Argentina, Australia, Austria, Belgium, Brazil, Canada, Chile, China, Colombia, Czechia, Denmark, Finland, France, Germany, Gibraltar, Hong Kong, India, Ireland, Italy, Japan, Kenya, Luxembourg, Malaysia, Mexico, Netherlands, New Zealand, Nigeria, Norway, Philippines, Poland, Portugal, Singapore, Slovakia, Spain, Sweden, Switzerland, Turkey, United Kingdom, United States. Note that Data Source Verification success rates vary by country. For more details on a specific country, contact your account manager. If you are running Data Source Verification checks on users outside the US, you may wish to use Documentary Verification as a fallback method in order to increase verification success rates. Selfie Checks and Documentary Verification are available in all supported countries. #### Supported documents  Document Verification supports over 16,000 distinct government-issued identification document types. You can check which document types are supported in a specific country from the Dashboard. From the Template Editor, under the **Workflow** tab, click **Assign Countries** and either add a new country or select one of the countries you've already configured for the template. Click **Physical Document Collection Options** to see which document types are supported for this country. #### Data retention and redaction  Identity Verification will retain data about user sessions as long as you maintain an active Identity Verification contract with Plaid. To request that user personally identifiable information (PII) be redacted on a rolling basis, such as after 90 days, contact support or your Plaid account manager to request a custom retention period. Redaction is permanent, and once you have set up a custom retention period, you cannot regain access to redacted data. You can also redact data on an ad-hoc basis via the Dashboard. If you end your contract with Plaid, you will lose access to the Identity Verification Dashboard and API, including access to information about previous sessions. If your use case requires that you retain user session data after your contract ends, use the API (via [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) and [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) ) to export the data prior to the end of your contract. #### Protect Dashboard  The [Protect Dashboard](https://dashboard.plaid.com/sandbox/protect) is an alternative UI for managing Identity Verification rules and viewing activity. (An image of "no description available") Example Protect Dashboard main page The Protect Dashboard provides capabilities not available in the Identity Verification Dashboard, including configurable workflows and approval logic based on custom rule groups. Rule groups can reference over 100 user attributes, including Trust Index score, location, age, and email domain. You can query this data directly using custom filters. For example, creating a filter such as "Trust Index < 30" or "more than 5 unique IP addresses" immediately returns matching live and historical sessions. These same filter criteria and user attributes can also be used to create rule groups, which you can then use in your approval logic via the "Configure" tab. For example, a rule group can be used to create a workflow that rejects users under a specified age or requires a higher Trust Index score for sessions originating from a specific country. Running a search shows which historical sessions would have matched the rule group, effectively backtesting the logic against production traffic. From any aggregated view, you can drill into an individual session to see the full event timeline and signal values used in decisioning. Data can be exported for audits, compliance, or downstream analysis. To access the Protect Dashboard, click the "Protect" icon on the left hand navigation pane of the Dashboard. The Protect Dashboard is available for all Identity Verification customers based in the US or UK. Identity Verification customers will have the following limitations when using the Protect Dashboard: * Only two weeks of history is available to search or visualize * Only two custom rule groups can be created To upgrade to two years of history and unlimited ruleset groups, [Contact sales](https://plaid.com/contact/) or your account manager to learn more about Protect. #### Testing Identity Verification  For more information about testing Identity Verification in Sandbox, see [Testing Identity Verification](https://plaid.com/docs/identity-verification/testing/index.html.md) . #### Sample app and additional resources  For a sample integration, see the [Identity Verification Quickstart](https://github.com/plaid/idv-quickstart) on GitHub. The PDF resources below provide an in-depth view of IDV integration and configuration options. Note that they are not updated as frequently as the docs and may not reflect the most recent updates to Identity Verification capabilities. * [Identity Verification and Monitor no-code guide](https://plaid.com/documents/idv-monitor-no-code-testing-guide.pdf) : A walkthrough of setting up a Identity Verification and Monitor integration with no code, using the [verification links](https://plaid.com/docs/identity-verification/index.html.md#verification-links-hosted-flow) option. This demo flow can help you quickly work with Identity Verification and Monitor and try out the end-user and admin experiences. #### Identity Verification pricing  Identity Verification has a base fee for every verification attempted, as well as separate fees for Data Source verification, Selfie checks, and Document checks. For more details, see the [Identity Verification fee model](https://plaid.com/docs/account/billing/index.html.md#identity-verification-fee-model) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . #### Next steps  To learn more about building with Identity Verification, see the [Identity Verification API Reference](https://plaid.com/docs/api/products/identity-verification/index.html.md) . If you're ready to launch to Production, see the Launch Center. #### Launch Center  See next steps to launch in Production [Launch](https://dashboard.plaid.com/developers/launch-center) --- # Identity Verification - Link callbacks | Plaid Docs Link callbacks  =============== #### Guide to using Link callbacks in your integration  After integrating Identity Verification using Link, you can use Link's client-side callbacks to see how your users are progressing through the flow. Note that you will not be able to access these if you use the Plaid-hosted flow with shareable links. [onSuccess](https://plaid.com/docs/link/web/index.html.md#link-web-create-onSuccess) will fire when a user has successfully completed the Link flow. The `link_session_id` returned by `onSuccess` can be passed to [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) in the `identity_verification_id` field to retrieve data on the verification. Note that receiving `onSuccess` simply means that the user completed the Identity Verification flow, not that their identity was verified. A completed session in which a user fails Identity Verification will still result in `onSuccess`. [onExit](https://plaid.com/docs/link/web/index.html.md#link-web-create-onExit) will fire when a user exits a session without finishing all required steps. If you receive this event, you may want to provide an option for the user to restart the Link flow, and/or provide guidance on manually performing KYC. [onEvent](https://plaid.com/docs/link/web/index.html.md#link-web-create-onEvent) will fire at certain points throughout the IDV flow with updates on the user's progress at each point. For each step, Plaid will send an [IDENTITY\_VERIFICATION\_START\_STEP](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-START-STEP) event as well as a [IDENTITY\_VERIFICATION\_PASS\_STEP](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-PASS-STEP) or [IDENTITY\_VERIFICATION\_FAIL\_STEP](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-FAIL-STEP) event based on the outcome of the step. Each step will also have an associated `view_name`. The possible view names include: [ACCEPT\_TOS](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-ACCEPT-TOS) , [VERIFY\_SMS](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-VERIFY-SMS) ,[KYC\_CHECK](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-KYC-CHECK) , [DOCUMENTARY\_VERIFICATION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-DOCUMENTARY-VERIFICATION) , [RISK\_CHECK](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-RISK-CHECK) , and [SELFIE\_CHECK](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-metadata-view-name-SELFIE-CHECK) . For each session, Plaid will also inform you of the outcome of the session by sending an [IDENTITY\_VERIFICATION\_PASS\_SESSION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-PASS-SESSION) or [IDENTITY\_VERIFICATION\_FAIL\_SESSION](https://plaid.com/docs/link/web/index.html.md#link-web-onevent-eventName-IDENTITY-VERIFICATION-FAIL-SESSION) event based on the outcome of the session. Note that, aside from `IDENTITY_VERIFICATION_PASS_SESSION` and `IDENTITY_VERIFICATION_FAIL_SESSION`, the sequence of view names and `onEvent` events are subject to change without notice, as Plaid adds additional functionality and makes improvements to flows. You should treat view names as informational and not rely on them for critical business logic. --- # Identity Verification - Metrics and reporting | Plaid Docs Generating metrics  =================== #### Generating metrics for Identity Verification  You can view the status of any Identity Verification session in the Dashboard. To obtain aggregated data such as the percentage of sessions that were completed or the percentage that passed verification vs. were rejected, you will need to use the API to generate the data. #### Conversion and success rates  The _conversion rate_ is defined as the percentage of sessions begun that were completed, regardless of whether the user passed or failed verification. The _success rate_ is defined as the percentage of completed sessions that resulted in the user passing verification. #### Calculating success rates  The most comprehensive way to measure overall success rates is to use [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) , since it includes backend-only sessions, sessions generated using shareable links, and manual overrides after the session is completed. If the status is `success`, the verification succeeded. If the status is `failed` or `pending review`, the verification did not succeed. The success rate is the number of sessions with the `success` status divided by the total of all sessions with the `success`, `failed`, or `pending review` status. Sessions with a status other than `success`, `failed`, or `pending review` should be discarded for the purpose of calculating overall success rates, since they represent sessions that were not completed. #### Calculating conversion rates  If you want to measure the conversion rate, you can use the `onEvent` callback. A session is started if you receive the `IDENTITY_VERIFICATION_START_STEP` event. It was completed if you receive either the `IDENTITY_VERIFICATION_PASS_SESSION` or `IDENTITY_VERIFICATION_FAIL_SESSION` event, and it was successful only if you receive the `IDENTITY_VERIFICATION_PASS_SESSION`. To correlate different events with the same Link session, use the `link_session_id`. For more details, see [Link callbacks](https://plaid.com/docs/identity-verification/link/index.html.md) . For Identity Verification, `onEvent` callback information is not available via the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint. Alternatively, you can calculate conversion using [/identity\_verification/get](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationget) . The conversion rate is the number of sessions with a status of `success`, `failed`, or `pending review` divided by the total number of unique identity verification IDs. Because this metric includes sessions where the result was manually overridden, as well as backend-only sessions, it will provide different results from Link-based conversion metrics, especially if you use a combination of backend-based sessions and Link-based sessions. Whether it makes more sense to report on overall conversion or Link-based conversion will depend on your use case. --- # Identity Verification - Risk checks | Plaid Docs Risk checks  ============ #### Understand what each Risk Check means and factors that influence results  This page outlines the various checks performed in the Risk Check category to help you understand the results and what Identity Verification evaluates during each check. For each session's risk check results, the Identity Verification Dashboard will show the largest factors contributing to the risk. #### Email Risk  Identity Verification does not collect an email address during the Link flow. Email risk will only be assessed if you collect the end user's email address and provide it to Plaid via [/identity\_verification/create](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationcreate) or [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Only verified email addresses should be sent for email risk assessment. Attributes that increase email risk include: * Email provided via a disposable email service, such as Mailinator. This is a strong fraud signal. * Email associated with a recently-registered (<3 months old) domain. * Email domain not deliverable. We do a live check on the domain to see if it is configured to receive email. Failing this test means the email is fake, which is a strong fraud signal. * Email not present on breach lists or only present on newer breaches (presence on older lists indicates an older, established, actively-used email address) * Email registered with few or no popular services, such as social media platforms. We check over 90 services for connections. In the Dashboard, all of the services that the email is detected as associated with will be displayed. #### Device risk  Plaid looks at multiple attributes of the end user's device. Attributes that can increase device risk include: | Risk factor | Contribution to device risk | | --- | --- | | Proxy usage | Moderate | | VPN usage | Moderate | | Tor usage | High | | IP address matching known-malicious IP lists | High | | Datacenter IP address (correlated with abuse) | High | | IP address geolocation mismatch vs KYC data or device time zone | Moderate | | Suspicious open ports | Moderate | | Incognito sessions | Moderate | | Cookies disabled | Moderate | | Large number of sessions / devices (indicative of fraud ring / account farm) | High | #### Identity Verification Network Risk  In Sandbox, when testing, make sure to lower risk thresholds for Network Risk, as normal testing behavior can trigger the Identity Verification Network Risk Check. Plaid creates a device fingerprint based on device/session attributes, including IP address, location, browser plugins, OS settings, WebGL parameters, user agent, TCP settings, cookies, screen resolution, battery usage, and device memory. The fingerprint allows Plaid to identify when the same device is used for multiple Identity Verification sessions. Plaid tracks the velocity of sessions per device across all customers. If a device is onboarding with many different Plaid clients in a short timeframe, this suggests coordinated fraud attempts. The dashboard will show counts for sessions in the last 24 hours, 7 days, 3 months, and all-time. If a device is seen creating multiple accounts in a short period (e.g. several signups in one day), this is also flagged as high risk, since it is often indicative of fraud rings or account farming. #### Phone risk  Phone risk checks for throwaway / burner phone numbers. Plaid checks for phone number registration with over 90 services. More links indicates lower risk. #### Stolen identity risk and synthetic identity risk  Stolen identity risk and synthetic identity risk will be assessed only for US end users, and only if a full 9-digit Social Security Number is available. Note that while stolen and synthetic identity risk are displayed in the Dashboard as percentages, the numbers do not indicate a percentage likelihood that the identity is stolen or synthetic. Instead, they merely represent that the score is normalized to be in the 0-100 range. A score of 70% or higher for synthetic identity, or a score of 90% or higher for stolen identity, indicates high risk. Risk factors for stolen identity include: * Multiple different identities associated with the same phone number, email, or SSN * PII associated with deceased individual (e.g. SSN found in Death Master File) Risk factors for synthetic identity include: * Multiple different identities associated with the same phone number, email, or SSN * PII associated with deceased individual (e.g. SSN found in Death Master File) * SSN inconsistent with date of birth or address history * Brief or no established usage of email address, phone number, or SSN (see [phone risk](https://plaid.com/docs/identity-verification/risk-checks/index.html.md#phone-risk) and [email risk](https://plaid.com/docs/identity-verification/risk-checks/index.html.md#email-risk) for more details on how usage history for these values is established) #### Facial duplicate risk  Facial duplicate risk will be assessed only if either Selfie Checks or Document Verification is enabled. Facial duplicate risk detects of user whose facial biometrics (from selfies or ID document portraits) match those from previous verification sessions. This is designed to catch repeat fraud attempts, synthetic identity attacks, and incentive abuse. #### Behavior risk  Behavior risk analyzes a user's behavior to determine whether it appears human and genuine. Factors analyzed include: * How fast a user types in their PII * How accurately a user enters their PII * Whether the data is copied and pasted * The field order in which a user inputs data * Mouse movement and scrolling patterns * The use of autofill * The frequency and device variety of entering the same or similar PII (see also [network risk](https://plaid.com/docs/identity-verification/risk-checks/index.html.md#identity-verification-network-risk) ). These are categorized into three risk buckets. **Behavior:** "Risky" means the user's interaction with the form is statistically anomalous compared to legitimate users, but does not necessarily show signs of being a bot or a fraud ring. For example, users typically enter their own PII fluently, so entering PII with hesitation or multiple corrections may indicate stolen identity. **Fraud Ring:** "Yes" means the session matches known fraud ring patterns. For example, repeatedly entering and correcting similar PII on a single device or across multiple devices simultaneously can indicate a fraud ring attempting a synthetic identity attack. **Bot:** "Yes" means the session exhibited patterns associated with non-human, non-autofill, automated data entry. --- # Identity Verification - Testing in Sandbox | Plaid Docs Testing in Sandbox  =================== #### Test values and options for Identity Verification  Identity Verification is not available by default in the Sandbox environment. To obtain Sandbox access, [request full Production access for Identity Verification](https://dashboard.plaid.com/settings/team/products) , which will automatically grant Sandbox access, or [contact sales](https://plaid.com/products/identity-verification/#contact-form) . To obtain Sandbox access for Identity Verification if you are already using another Plaid product, you can also contact your account manager or submit an [access request ticket](https://dashboard.plaid.com/support/new/admin/account-administration/request-product-access) . #### Sandbox users for Identity Verification  ##### Primary test user (Leslie Knope)  In Sandbox mode, Identity Verification accepts the fixed set of inputs below in order to result in successful Data Source and Document Verification checks. | Form Field | Test Value | | --- | --- | | Mobile number | +1 234-567-8909 | | First name | Leslie | | Last name | Knope | | Verification code | 11111 | | Address | 123 Main St. | | City | Pawnee | | State | Indiana | | ZIP code | 46001 | | Month | January | | Day | 18 | | Year | 1975 | | SSN | 123-45-6788 or 123-45-6789 | ##### Custom test users  For US verifications, Plaid supports creating custom test users from your organization directly in Sandbox. Custom test users can be managed on the Identity Verification page in the Dashboard, under [Sample Identities](https://dashboard.plaid.com/sandbox/identity_verification/sample_identities) , allowing you to test your own sets of PII to result in successful Data Source and Document Verification checks. The following names are reserved and cannot be used for custom sample identities: * Leslie Knope * Jerry Gergich (or any first name used with the surname Gergich, such as Larry Gergich, Terry Gergich, etc.) #### Identity verification behavior in Sandbox  ##### Data Source checks  Data Source checks in Sandbox will be compared against the information above. To simulate different test cases and results, you can adjust your Data Source input at the attribute level (e.g. an incorrect birthdate), and set up different Identity Rules to simulate different verification results. ##### Document checks  Documents uploaded in Sandbox will always be interpreted as genuine (not fake) documents reflecting the name and date of birth matching the Leslie Knope test user. Document check will pass if the data provided in the Data Source check matches this name and date of birth, and will fail otherwise. Users have three attempts to pass the Document check, so the status will not be updated in the Dashboard to `failed` until you have provided mismatching data three times. ##### Selfie checks  Selfie checks will not be run in Sandbox mode, even if they are enabled in your template. ##### AML Screening  In Sandbox, Monitor screens against a real-world dataset, so the Sandbox user will not return any screening hits. For more information, including example data you can use to trigger screening hits, see [Testing Monitor](https://plaid.com/docs/monitor/index.html.md#testing-monitor) . ##### Risk Check  The risk check is fully functional in Sandbox. It's common to trigger high risk scores when testing. For more information and advice, see [Risk rules for testing](https://plaid.com/docs/identity-verification/testing/index.html.md#risk-rules-for-testing) . ##### Auto-fill  Auto-fill behavior is fully functional in Sandbox. ##### Financial Account Matching  Financial Account Matching is fully functional in Sandbox. If you want to change the Identity data that is being compared to the Identity Verification session, see [how to create Sandbox test data](https://plaid.com/docs/sandbox/user-custom/index.html.md) . #### Risk rules for testing  Many common testing behaviors (e.g. attempting to enter the Identity Verification flow repeatedly on the same device using different credentials) may be flagged as risky behavior and cause your verification attempt to fail. For testing purposes, you can temporarily set the Acceptable Risk Level for any checks you are failing (typically Network Risk and Device Risk) to **High**, under the **Rulesets -> Risk Rules** section of the template editor. Make sure to set the Acceptable Risk Level back to your desired setting before launching in Production. If you want to force a check to fail in Sandbox, an easy way to do this is to set Acceptable Risk Level for the Network Risk and Device Risk fields to **Low**. Checks will begin failing after your first few attempts. #### Triggering specific test outcomes  Using the rules above, it is easy to create the outcome of passing both Data Source checks and Document checks, or of failing both checks. If you need to simulate specific combinations of pass / fail (passing one check but not the other), you can use the guides below. ##### Data Source check passes, Document Verification check fails  1. Set up your template to always be enabled for Data Source checks and Document Checks. 2. Set up your template to not require a match or partial match on name or date of birth. 3. Enter Leslie Knope's correct test data, or a sample identity you have configured in the Dashboard, for the address, SSN, and phone number fields. 4. Enter incorrect data for the name and date of birth fields. If you would like this test to also trigger a Monitor hit, you can use the name and date of birth of a sanctioned individual. For examples, see [Monitor test data](https://plaid.com/docs/monitor/index.html.md#testing-monitor) . ##### Data Source check fails, Document Verification check passes  1. Set up your template to be enabled for Data Source checks, with Document checks as a fallback. 2. Set up your template to require a match for address, SSN, and phone number fields. 3. Enter Leslie Knope's correct test data, or a sample identity you have configured in the Dashboard, for the name and date of birth fields. 4. Enter incorrect data for the address, SSN, and phone number fields. #### Testing Financial Account Matching  1. Create a template with Financial Account Matching enabled. 2. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with `identity_verification` in the `products` array. Make sure to save the `client_user_id` you are using with this call, as you will need it later. 3. Launch Link and complete the Identity Verification session, entering Leslie Knope's correct test data. 4. See the [Sandbox custom user repo](https://github.com/plaid/sandbox-custom-users/tree/main) for instructions on configuring custom Sandbox users and create a custom user using the [Financial Account Matching custom user data](https://github.com/plaid/sandbox-custom-users/blob/main/identity/leslie_knope_financial_account_matching.json) from that repo. 5. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with `identity` (or `assets`, for underwriting use cases) in the `products` array and the same `client_user_id` as was used in the first step, and launch a Link session. 6. Use the custom user you created above to log in to Link, then call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the public token for an access token. 7. Call [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) or [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) (or [/asset\_report/create](https://plaid.com/docs/api/products/assets/index.html.md#asset_reportcreate) , if using `assets` instead of `identity`) on the access token. 8. Check the Identity Verification session in the Dashboard. You should see the linked account and a successful match in the Financial Account Matching section. --- # Identity Verification - Webhooks | Plaid Docs Webhooks  ========= #### Subscribe to events and get real-time alerts for changes  Once you have Link with Identity Verification embedded in your app, you should be able to complete an entire session and review it in the dashboard. To complete your integration, you need to add a webhook receiver endpoint to your application. To add a webhook, visit the [dashboard webhook configuration page](https://dashboard.plaid.com/developers/webhooks) and click **New Webhook**. Note that this is the only setting used to configure Identity Verification webhook receivers; webhook URLs set via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) will not be used. You can select which events you want to subscribe to. For Identity Verification, there are three events: * [STEP\_UPDATED](https://plaid.com/docs/api/products/identity-verification/index.html.md#step_updated) * [STATUS\_UPDATED](https://plaid.com/docs/api/products/identity-verification/index.html.md#status_updated) * [RETRIED](https://plaid.com/docs/api/products/identity-verification/index.html.md#retried) Enter your webhook receiver endpoint for the webhook you wish to subscribe to and click **Save**. Plaid will now send an HTTP POST request to the webhook receiver endpoint every time the event occurs, in both the Sandbox and Production environments. If multiple webhook receiver endpoints are configured for an Identity Verification event, webhooks will be sent to all the configured endpoints. #### Event ordering  Identity Verification does not guarantee that webhooks will be delivered in any particular order. For example, while the logical ordering of webhooks for a Identity Verification session might look like this: 1. `STEP_UPDATED` The user has started the Identity Verification session and is on the first step 2. `STEP_UPDATED` 3. `STATUS_UPDATED` The user has reached a terminal state for their session 4. `RETRIED` A retry has been requested for this user, either via the dashboard or via API 5. `STEP_UPDATED` 6. `STEP_UPDATED` 7. `STATUS_UPDATED` The retry has been completed you should be prepared to handle these events in any delivery order. For example, consider whether your application will properly handle: * A `STEP_UPDATED` event being delivered after a `STATUS_UPDATED` event. * A `STEP_UPDATED` event being delivered before an associated `RETRIED` In order to properly handle webhook events being delivered out of order, your application should lookup the user's associated session(s) via the [/identity\_verification/list](https://plaid.com/docs/api/products/identity-verification/index.html.md#identity_verificationlist) API. #### Webhook Reference  For full webhook information, refer to the [API Documentation](https://plaid.com/docs/api/products/identity-verification/index.html.md) . --- # Identity - Add Identity to your app | Plaid Docs Add Identity to your app  ========================= #### Use Identity to verify user data  In this guide, we'll start from scratch and walk through how to use [Identity](https://plaid.com/docs/api/products/identity/index.html.md) to retrieve identity data. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to [Matching identity data](https://plaid.com/docs/identity/add-to-app/index.html.md#matching-identity-data) (for [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) ) or [Fetching identity data](https://plaid.com/docs/identity/add-to-app/index.html.md#fetching-identity-data) (for [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) ). #### Get Plaid API keys and complete application and company profile  If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard. You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile and company profile must be completed before connecting to certain institutions in Production. #### Install and initialize Plaid libraries  You can use our official server-side client libraries to connect to the Plaid API from your application: ```node // Install via npm npm install --save plaid ``` ```bash ## Not applicable with curl calls ``` ```ruby # Available as a gem gem install plaid ``` ```java /* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ implementation "com.plaid:plaid-java:{VERSION}" /* For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ com.plaid plaid-java {VERSION} ``` ```python # Install through pip, only supports Python 3 pip install --upgrade plaid-python ``` ```go go get github.com/plaid/plaid-go ``` After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls. In the code samples below, you will need to replace `PLAID_CLIENT_ID` and `PLAID_SECRET` with your own keys, which you can obtain from the [Dashboard](https://dashboard.plaid.com/developers/keys) . These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask). ```node // Using Express const express = require('express'); const app = express(); app.use(express.json()); const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const client = new PlaidApi(configuration); ``` ```bash ## Not applicable with curl calls ``` ```ruby require 'sinatra' require 'plaid' set :port, ENV['APP_PORT'] || 8000 configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) ``` ```java import java.net.*; import java.io.*; import retrofit2.Response; import java.util.Arrays; import com.sun.net.httpserver.*; import com.plaid.client.ApiClient; import com.plaid.client.request.PlaidApi; public class PlaidExample { private static final String CLIENT_ID = System.getenv("PLAID_CLIENT_ID"); private static final String SECRET = System.getenv("PLAID_SECRET"); public static void main(String[] args) { HttpServer server = HttpServer.create( new InetSocketAddress("localhost", 8000), 0); server.createContext("/create_link_token", new GetLinkToken()); server.setExecutor(null); server.start(); } // Additional server code goes here } ``` ```python import plaid from plaid.api import plaid_api from flask import Flask from flask import render_template from flask import request from flask import jsonify app = Flask(name) configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Additional server code goes here if __name__ == "__main__": app.run(port=8000) ``` ```go import ( "context" "net/http" "os" "github.com/gin-gonic/gin" "github.com/plaid/plaid-go/v3/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) func main() { r := gin.Default() // Server endpoints would be declared here // e.g. r.POST("/create_link_token", createLinkToken) r.POST("/create_link_token", createLinkToken) err := r.Run(":8000") if err != nil { panic("unable to start server") } } ``` #### Create an Item in Link  Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) . Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created. ##### Create a link\_token  ```node app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['identity'], language: 'en', webhook: 'https://webhook.example.com', redirect_uri: 'https://domainname.com/oauth-page.html', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "products": ["identity"], "country_codes": ["US"], "language": "en", "webhook": "https://webhook.example.com", "redirect_uri": "https://domainname.com/oauth-page.html" }' ``` ```ruby post '/api/create_link_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: client_user_id }, client_name: 'Plaid Test App', products: ['identity'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.example.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.Products; import com.plaid.client.model.CountryCode; import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; public class PlaidExample { ... static class GetLinkToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.fromValue("identity"))) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .redirectUri("https://domainname.com/oauth-page.html") .webhook("https://webhook.example.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.link_token_create_request import LinkTokenCreateRequest from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser from plaid.model.products import Products from plaid.model.country_code import CountryCode @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( products=[Products("identity")], client_name="Plaid Test App", country_codes=[CountryCode('US')], redirect_uri='https://domainname.com/oauth-page.html', language='en', webhook='https://webhook.example.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetRedirectUri("https://domainname.com/oauth-page.html") request.SetProducts([]plaid.Products{plaid.PRODUCTS_IDENTITY}) resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` ##### Install Link dependency  index.html ```html Connect a bank ``` ##### Configure the client-side Link handler  app.js ```javascript const linkHandler = Plaid.create({ token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token to your app server. $.post('/exchange_public_token', { public_token: public_token, }); }, onExit: (err, metadata) => { // Optionally capture when your user exited the Link flow. // Storing this information can be helpful for support. }, onEvent: (eventName, metadata) => { // Optionally capture Link flow events, streamed through // this callback as your users connect an Item to Plaid. }, }); linkHandler.open(); ``` #### Get a persistent access\_token  Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call. Save the `access_token` and `item_id` in a secure datastore, as they're used to access `Item` data and identify `webhooks`, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it. ```node app.post('/api/exchange_public_token', async function ( request, response, next, ) { const publicToken = request.body.public_token; try { const tokenResponse = await client.itemPublicTokenExchange({ public_token: publicToken, }); // These values should be saved to a persistent database and // associated with the currently signed-in user const accessToken = tokenResponse.data.access_token; const itemID = tokenResponse.data.item_id; response.json({ public_token_exchange: 'complete' }); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-12345678-abcd-1234-abcd-1234567890ab" }' ``` ```ruby access_token = nil post '/api/exchange_public_token' do request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: params["public_token"] } ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response.access_token item_id = response.item_id content_type :json {public_token_exchange: "complete"}.to_json end ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; public class PlaidExample { ... static class GetAccessToken implements HttpHandler { private static PlaidClient plaidClient; private String publicToken; private String accessToken; private String itemId; public void handle(HttpExchange t) throws IOException { // Simplified pseudo-code for obtaining public_token InputStream is = t.getRequestBody(); publicToken = is.publicToken(); // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange public_token for an access_token ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response response = plaidClient .itemPublicTokenExchange(request) .execute(); // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken = response.body().getAccessToken(); itemId = response.body().getItemId(); String message = "{\"public_token_exchange\": \"complete\"}"; return Response .status(Response.Status.OK) .entity(message) .type(MediaType.APPLICATION_JSON) } } } ``` ```python access_token = None item_id = None @app.route('/exchange_public_token', methods=['POST']) def exchange_public_token(): global access_token public_token = request.form['public_token'] request = ItemPublicTokenExchangeRequest( public_token=public_token ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response['access_token'] item_id = response['item_id'] return jsonify({'public_token_exchange': 'complete'}) ``` ```go func getAccessToken(c *gin.Context) { ctx := context.Background() publicToken := c.PostForm("public_token") // exchange the public_token for an access_token exchangePublicTokenReq := plaid.NewItemPublicTokenExchangeRequest(publicToken) exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *exchangePublicTokenReq, ).Execute() // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken := exchangePublicTokenResp.GetAccessToken() itemID := exchangePublicTokenResp.GetItemId() c.JSON(http.StatusOK, gin.H{"public_token_exchange": "complete"}) } ``` Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. #### Matching Identity data  To match Identity data, call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) . If you are using [Identity Verification](https://plaid.com/docs/api/products/identity-verification/index.html.md) , you can automatically match data from the linked account against data collected during the Identity Verification flow. To enable this setting, from the Identity Verification section of the Dashboard, access the template editor and on the "Setup" pane of the template, check the box under the "Financial Account Matching" header. If this option is selected, you should call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) with only an `access_token` to obtain match scores. If you are not using [Identity Verification](https://plaid.com/docs/api/products/identity-verification/index.html.md) , you will need to send the identity information that you have on file and would like to match against, such as name, phone number, and address, as part of your call to [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) . ```ruby # Omit user object if using identity verification / financial account matching user = Plaid::IdentityMatchUser.new( legal_name: 'Jane Smith', phone_number: '+14155552671', email_address: 'jane.smith@example.com', address: Plaid::AddressDataNullableNoRequiredFields.new( street: '500 Market St', city: 'San Francisco', region: 'CA', postal_code: '94105', country: 'US' ) ) request = Plaid::IdentityMatchRequest.new( access_token: access_token, user: user ) response = client.identity_match(request) accounts = response.accounts accounts.map do |account| name_score = account.legal_name&.score phone_score = account.phone_number&.score email_score = account.email_address&.score address_score = account.address&.score end ``` ```bash curl -X POST https://sandbox.plaid.com/identity/match \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String, "user": { "phone_number": String, "legal_name": String, "email_address": String, "address": { "street": String, "region": String, "country": String, "city": String, "postal_code": String } } }' ``` ```node const request = { access_token: accessToken, // Omit user object if using Identity Verification / Financial Account Matching user: { legal_name: 'Jane Smith', phone_number: '+14155552671', email_address: 'jane.smith@example.com', address: { street: '500 Market St', city: 'San Francisco', region: 'CA', postal_code: '94105', country: 'US', }, }, }; try { const response = await plaidClient.identityMatch(request); const accounts = response.data.accounts; for (const account of accounts) { const legalNameScore = account.legal_name?.score; const phoneScore = account.phone_number?.score; const emailScore = account.email_address?.score; const addressScore = account.address?.score; } } catch (error) { // handle error } ``` ```java // Match identity provided by client against bank/account identity // Omit user object if using Identity Verification / Financial Account Matching IdentityMatchUser user = new IdentityMatchUser() .legalName("Jane Smith") .phoneNumber("+14155552671") .emailAddress("jane.smith@example.com") .address(new AddressDataNullableNoRequiredFields() .street("500 Market St") .city("San Francisco") .region("CA") .postalCode("94105") .country("US")); IdentityMatchRequest request = new IdentityMatchRequest() .accessToken(accessToken) .user(user); Response response = plaidClient.service().identityMatch(request).execute(); List accounts = response.body().getAccounts(); for (IdentityMatchResponse.AccountIdentityMatchScores account : accounts) { Integer legalNameScore = account.getLegalName() != null ? account.getLegalName().getScore() : null; Integer phoneNumberScore = account.getPhoneNumber() != null ? account.getPhoneNumber().getScore() : null; Integer emailAddressScore = account.getEmailAddress() != null ? account.getEmailAddress().getScore() : null; Integer addressScore = account.getAddress() != null ? account.getAddress().getScore() : null; // Compare scores to risk thresholds } ``` ```python # Omit user object if using Identity Verification / Financial Account Matching user = IdentityMatchUser( legal_name="Jane Smith", phone_number="+14155552671", email_address="jane.smith@example.com", address=AddressDataNullableNoRequiredFields( street="500 Market St", city="San Francisco", region="CA", postal_code="94105", country="US" ) ) request = IdentityMatchRequest( access_token=access_token, user=user ) response = client.identity_match(request) accounts = response['accounts'] for account in accounts: name_score = account['legal_name']['score'] if account['legal_name'] is not None else None phone_score = account['phone_number']['score'] if account['phone_number'] is not None else None email_score = account['email_address']['score'] if account['email_address'] is not None else None address_score = account['address']['score'] if account['address'] is not None else None ``` ```go // Omit user object if using Identity Verification / Financial Account Matching user := plaid.IdentityMatchUser{} user.SetLegalName("Jane Smith") user.SetPhoneNumber("+14155552671") user.SetEmailAddress("jane.smith@example.com") address := plaid.AddressDataNullableNoRequiredFields{} address.SetStreet("500 Market St") address.SetCity("San Francisco") address.SetRegion("CA") address.SetPostalCode("94105") address.SetCountry("US") user.SetAddress(address) request := plaid.NewIdentityMatchRequest(accessToken) request.SetUser(user) response, _, err := client.PlaidApi.IdentityMatch(ctx).IdentityMatchRequest(*request).Execute() if err != nil { log.Fatal(err) } accounts := response.GetAccounts() for _, account := range accounts { if legalName, ok := account.GetLegalNameOk(); ok { legalNameScore := legalName.GetScore() _ = legalNameScore } if phoneNumber, ok := account.GetPhoneNumberOk(); ok { phoneScore := phoneNumber.GetScore() _ = phoneScore } if emailAddress, ok := account.GetEmailAddressOk(); ok { emailScore := emailAddress.GetScore() _ = emailScore } if address, ok := account.GetAddressOk(); ok { addressScore := address.GetScore() _ = addressScore } } ``` The call to [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) will return a match score for each field that was evaluated. Typically, your threshold to accept the field as a match should be set to at least 70. For more details, see the [match score table](https://plaid.com/docs/identity/index.html.md#sample-identity-match-data) . Identity Match sample response ```json { "accounts": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": null, "current": null, "iso_currency_code": null, "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "legal_name": { "score": 90, "is_nickname_match": true, "is_first_name_or_last_name_match": true, "is_business_name_detected": false }, "phone_number": { "score": 100 }, "email_address": { "score": 100 }, "address": { "score": 100, "is_postal_code_match": true }, "subtype": "checking", "type": "depository" }, { "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr", "balances": { "available": null, "current": null, "iso_currency_code": null, "limit": null, "unofficial_currency_code": null }, "mask": "1111", "name": "Plaid Saving", "official_name": "Plaid Silver Standard 0.1% Interest Saving", "legal_name": { "score": 30, "is_first_name_or_last_name_match": false }, "phone_number": { "score": 100 }, "email_address": null, "address": { "score": 100, "is_postal_code_match": true }, "subtype": "savings", "type": "depository" } ], ... } ``` #### Fetching Identity data  If you are not using Identity Match, call [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) to obtain Identity data. You will need to implement your own matching algorithm to determine whether the data returned matches the information that you have on file about the user. For more detailed information on the schema returned, see [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) . ```ruby require 'plaid' # pull identity data for an item request = Plaid::IdentityGetRequest.new({ access_token: access_token }) response = client.identity_get(request) accounts = response.accounts identities = accounts.map { |account| account.owners }.flatten ``` ```bash curl -X POST https://sandbox.plaid.com/identity/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node const { IdentityGetRequest } = require('plaid'); // Pull Identity data for an Item const request: IdentityGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.identityGet(request); const identities = response.data.accounts.flatMap( (account) => account.owners, ); } catch (error) { // handle error } ``` ```java import com.plaid.client.model.IdentityGetResponse; // Pull Identity data for an Item // Java 7 List accounts = response.body().getAccounts(); List identities = new ArrayList<>(); for (IdentityGetResponse.AccountWithOwners account : accounts) { identities.addAll(account.getOwners()); } // Java 8 and above List accounts = response.body().getAccounts(); List identities = accounts.stream() .flatMap(account -> account.getOwners().stream()) .collect(Collectors.toList()); ``` ```python import plaid from plaid.model.identity_get_request import IdentityGetRequest # pull identity data for an item request = IdentityGetRequest(access_token=access_token) response = client.identity_get(request) accounts = response['accounts'] identities = [] for account in accounts: identities.extend(account['owners']) ``` ```go import ( "context" "github.com/plaid/plaid-go/v40/plaid" ) identityGetResp, _, err := client.PlaidApi.IdentityGet(ctx).IdentityGetRequest( *plaid.NewIdentityGetRequest(accessToken), ).Execute() accounts := identityGetResp.GetAccounts() ``` Example response data is below. Identity sample data ```json { "accounts": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true }, { "data": { "city": "San Matias", "country": "US", "postal_code": "93405-2255", "region": "CA", "street": "2493 Leisure Lane" }, "primary": false } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholder1@example.com", "primary": false, "type": "secondary" } ], "names": ["Alberta Bobbeth Charleson"], "phone_numbers": [ { "data": "1112223333", "primary": false, "type": "home" }, { "data": "1112224444", "primary": false, "type": "work" }, { "data": "1112225555", "primary": false, "type": "mobile1" } ] } ], "subtype": "checking", "type": "depository" } ], "item": { "available_products": ["balance", "credit_details", "investments"], "billed_products": [ "assets", "auth", "identity", "liabilities", "transactions" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_3", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "webhook": "https://www.genericwebhookurl.com/webhook" }, "request_id": "3nARps6TOYtbACO" } ``` #### Tutorial and example code in Plaid Pattern  For a real-life example of an app that incorporates Identity, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that fetches Identity data in order verify identity prior to a funds transfer. The Identity code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L81-L116) . For a tutorial walkthrough of creating a similar app, see [Account funding tutorial](https://github.com/plaid/account-funding-tutorial) . #### Next steps  If you're ready to launch to Production, see the Launch checklist. #### Launch checklist  Recommended steps to take before launching in Production [Launch](https://plaid.com/docs/launch-checklist/index.html.md) --- # Identity - Identity Document Upload | Plaid Docs Identity Document Upload  ========================= #### Learn about statement upload-based account ownership verification  #### Overview  In order to provide the user an additional way to verify their account ownership, Identity Document Upload can be used to upload a bank statement, verify that statement belongs to the account in question, and verify the ownership information on the statement. This feature is intended primarily for use with Items created via loginless Auth flows, such as Same-Day Micro-deposits, Instant Micro-deposits, or Database Insights. Identity Document Upload is available as an add-on to Identity. For pricing details, and to request access to Identity Document Upload, contact your Plaid account manager or sales. To detect potential document fraud or document tampering during the Identity Document Upload flow, you can use the optional Fraud Risk feature, which scans for over two dozen different fraud signals in categories such as visual evidence of tampering, suspicious metadata, inconsistent contents, and similarity to known fraudulent documents. #### Implementation  To use Document Upload, you will first create the Item with another product such as Auth or Transfer. Then, run Link in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) with the following parameters (in addition to the required fields): * The `products` array set to `["identity"]`. * The `identity.account_ids` array should contain the `account_id` of the account to verify. Currently, only one `account_id` can be specified. * `identity.is_document_upload` should be set to `true`. * (Optional) to enable Fraud Risk, set `identity.parsing_configs` to `["ocr", "risk_signals"]` Example /link/token/create call for Identity Document Upload ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Insert Client name here", "products": ["identity"], "access_token": "Insert access token here", "identity": { "is_document_upload": true, "account_ids": ["ZXEbW7Rkr9iv1qj8abebU1KDJlkexgSgrLAod"], "parsing_configs": ["ocr", "risk_signals"] }, "country_codes": ["US"], "language": "en", "user": { "client_user_id": "unique_user_id" } }' ``` During update mode, the end user will be prompted to upload a bank statement. After the statement has been uploaded and processed, Plaid will send an `IDENTITY: DOCUMENT_UPDATE_AVAILABLE` webhook. A `"document_status": "OCR_PROCESSING_COMPLETE"` field in the webhook body indicates that the statement was successfully parsed. If the parsing is successful, you can call [/identity/documents/uploads/get](https://plaid.com/docs/api/products/identity/index.html.md#identitydocumentsuploadsget) , which will return the identity data parsed from the document in the same format as [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) . This endpoint will also return a `documents` array -- for any given document in the array, if the `metadata.is_account_number_match` field is `true`, Plaid has verified that the account number on the document matches the account number known to Plaid. If it is `false`, the document does not substantiate the end user's ownership of the account. Documents array ```json "documents": [ { "document_id": "1d107b7f-91fe-44c8-b8e9-325494addf5d", "metadata": { "document_type": "BANK_STATEMENT", "is_account_number_match": true, "last_updated": "2024-01-29T08:06:46Z", "uploaded_at": "2024-01-29T08:06:46Z" }, "risk_insights": { "risk_signals": [ { "has_fraud_risk": true, "page_number": 0, "signal_description": "Creation date and modification date do not match", "type": "METADATA_DATES_OUTSIDE_WINDOW" }, { "has_fraud_risk": true, "page_number": 0, "signal_description": "Adobe Acrobat", "type": "SOFTWARE_BLACKLIST" } ], "risk_summary": { "risk_score": 100 } } } ], ``` If Fraud Risk was enabled, the `document` object will contain a `risk_insights` object, including details about potential risks detected in the uploaded document. The `risk_insights.risk_summary.risk_score` field will contain a score summarizing the risk of the document. If the score is 80 or higher, we recommend treating the account identity as unverified and potentially high risk and sending the user through a manual verification flow. ##### Testing Identity Document Upload  In the Sandbox, Plaid will not parse the uploaded bank statement and will instead return pre-populated test user data. Because of this, Sandbox will proceed much faster than Production; you should make sure your app can handle the asynchronous behavior of Production, in which the user's statement will be verified after they have completed Link, rather than during the Link session. In Sandbox, you must provide a valid webhook URI in order to upload documents. --- # Identity - Introduction to Identity | Plaid Docs Introduction to Identity   ========================== #### Verify users' account ownership and reduce fraud  Get started with Identity [API Reference](https://plaid.com/docs/api/products/identity/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md) #### Overview  Plaid's Identity product helps you verify users' identities by accessing information on file with their financial institution. Using Identity, you can access a user's phone number, email address, mailing address, and name. This can be used to fight fraud by verifying that the linked financial institution account is owned by the same user who created an account with you. [Prefer to learn by watching? Get an overview of how Identity works in just 3 minutes!](https://www.youtube.com/watch?v=ILSSdpgGBaU) Plaid provides two endpoints for Identity: * [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) retrieves the user's name and contact information from their financial institution * [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) allows you to provide a name and contact information for a user and returns a set of match scores indicating how well that information matches the information on file with their financial institution, simplifying the process of using identity data for account ownership verification. Both endpoints can be used to reduce fraud, improve user onboarding and conversion, and to complement Know Your Customer (KYC) compliance checks. Identity can be used to verify all major account types supported by Plaid, including checking and savings accounts, credit cards, brokerage accounts, and loans. Identity coverage can be used to verify an account before initiating an ACH transaction: 97% of Items initialized with [Auth](https://plaid.com/docs/auth/index.html.md) provide Identity data as well. Depending on your use case, you may want to verify the identity of all users, or only some. For example, you might want to verify the identity of any user initiating a funds transfer, or you might only verify users who you have identified as being higher risk, based on data such as email address, location, financial institution, or activity patterns. Plaid Identity can be combined with [Plaid Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) in a single workflow to provide full identity verification and fraud reduction. [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) is used for KYC, to verify that the user of your app is the person they claim to be, while Identity is used to confirm that the ownership information on their linked bank or credit card account matches this verified identity. #### Integration overview  1. Create a Link token by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . * If you are using Identity as a best-effort adjunct to other products, like Auth, put `identity` in the `required_if_supported_products` array. * If you want to require Identity and fail sessions where Identity data is not available, put `identity` in the `products` array. 2. Initialize Link with the Link token from the previous step. For more details, see [Link](https://plaid.com/docs/link/index.html.md) . 3. Once the user has successfully completed the Link flow, exchange the `public_token` for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . 4. Once you have the `access_token`, call [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) to get data, or [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) to match data. For more information on [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , including optional streamlined integration modes, see [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) . #### Getting Identity data  The [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) endpoint provides you with several pieces of information. The name is guaranteed to be available; the email address, phone number, and address are usually available, but may be `null` otherwise. ##### Sample Identity data  Identity data returned by [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) includes owners' names, addresses, email addresses, and phone numbers as reported by the financial institution. In the case of an Item containing accounts with multiple owners, all owners' information will be provided. For business accounts, the account owner's name can be that of a business. Sample Identity data ```json "owners": [ { "addresses": [ { "data": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "primary": true } ], "emails": [ { "data": "accountholder0@example.com", "primary": true, "type": "primary" }, { "data": "accountholdersecondary0@example.com", "primary": false, "type": "secondary" } ], "names": [ "Alberta Bobbeth Charleson" ], "phone_numbers": [ { "data": "1112223333", "primary": true, "type": "home" } ] } ] ``` ##### Typical identity fill rates by field  | Field | Typical fill rate | | --- | --- | | Name | 100% | | Email address | 98% | | Address | 93% | | Phone number | 90% | #### Identity Match  Using [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , Identity data fields such as names, addresses, email addresses, and phone numbers can be matched against the owners' identity information on connected accounts. Multiple fields are matched in a single request, and a separate score is returned for each field to indicate how closely it matched. Customers using Identity Match can experience onboarding conversion improvements of 20% or more, without increasing fraud rates, when using Identity Match versus using their own matching algorithms. If you are using [Auth](https://plaid.com/docs/auth/index.html.md) , you can optionally integrate Identity Match via the Dashboard with no additional code. For details, see [Integrating Identity Match via the Account Verification Dashboard](https://plaid.com/docs/identity/index.html.md#integrating-identity-match-via-the-account-verification-dashboard) . (An image of "no description available") Example Identity Match results in the Account Verification Dashboard If you are already using [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) , you can further enhance your verification process by enabling Financial Account Matching in your Identity Verification template. This feature allows you to match the data collected during KYC without having to specify the `user` field in your [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) request. To ensure accurate matching, it's important to maintain consistency in the `client_user_id` used for end users across all products. ##### Sample Identity Match data  Data returned by [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) includes scores from matching a user's name, address, phone number, and email with the account owner's data that was present on the connected account. A score ranging from 0 to 100 is provided for each identity field. The score for a given field will be missing if the identity information for that field was not provided in the request or unavailable at the connected account. In the case of an Item containing accounts with multiple owners, the highest matched scores are returned. You should typically not set the match score requirement for a field to 100. For example, if a phone number match score of 100 is required, the presence or absence of a country code, parentheses, or other formatting differences may cause a phone number mismatch. 70 is the default recommended match score threshold for all fields. ###### Example of how to interpret name match score  | Range | Meaning | Example | | --- | --- | --- | | 100 | Exact match | Andrew Smith, Andrew Smith | | 85-99 | Strong match, likely spelling error, nickname, or a missing middle name, prefix or suffix | Andrew Smith, Andrew Simth | | 70-84 | Possible match, likely alias or nickname and spelling error | Andrew Smith, Andy Simth | | 50-69 | Unlikely match, likely relative | Andrew Smith, Betty Smith | | 0-49 | Unlikely match | Andrew Smith, Ray Charles | ###### Example of how to interpret phone number score  | Range | Meaning | Example | | --- | --- | --- | | 100 | Exact match | +1-555-867-5309, +1-555-867-5309 | | 90-99 | Same phone number, likely different formatting | +1-555-867-5309, 1 (555)-867-5309 | | 70-89 | Same phone number, likely different formatting and/or missing country code | +1-555-867-5309, 5558675309 | | 0-69 | Unlikely match | +1-555-867-5309, 555-867-5302 | Sample Identity match data ```json { "accounts": [ { .. "legal_name": { "score": 90, "is_nickname_match": true, "is_first_name_or_last_name_match": true }, "phone_number": { "score": 100 }, "email_address": { "score": 100 }, "address": { "score": 100, "is_postal_code_match": true } .. } ] } ``` ##### Using Identity Match with micro-deposit or database Items  Items verified via [Same Day micro-deposits](https://plaid.com/docs/auth/coverage/same-day/index.html.md) , [Instant micro-deposits](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-micro-deposits) , or [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) are not typically compatible with any other Plaid products besides Auth and Transfer. An exception is Identity Match, which can be used with these Items if they were previously seen on the Plaid network (approximately 30% of these Items). Note that this applies to the Identity Match endpoint only; Items created using these flows are not compatible with [/identity/get](https://plaid.com/docs/api/products/identity/index.html.md#identityget) . To use Identity Match with micro-deposit or database Items, you have two options: * For a low-code option that allows you to run the Identity Match check within the Link flow, use the [Account Verification Dashboard](https://plaid.com/docs/identity/index.html.md#integrating-identity-match-via-the-account-verification-dashboard) . * To run the Identity Match check outside the Link flow, continue with the [integration instructions in this section](https://plaid.com/docs/identity/index.html.md#integration-instructions) . ###### Integration instructions  1. To enable the Item for Identity Match, `identity` must be included in the `optional_products`, `required_if_supported_products`, or `additional_consented_products` array during the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call at Item creation. (For this flow, `identity` should not be included in the `products` array, since including any other product than `auth` in the `products` array can prevent micro-deposit or database verification flows from activating.) * If this was not done during Item creation, you can Identity consent to an existing Item by sending it through [update mode](https://plaid.com/docs/link/update-mode/index.html.md#requesting-additional-consented-products) . 2. Call [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) . If the Item is supported by Identity Match, you will receive results. If the Item was not previously seen on the Plaid network and therefore cannot be used with Identity Match, you will receive a `PRODUCTS_NOT_SUPPORTED` error and will not be billed for the API call. #### Integrating Identity Match via the Account Verification Dashboard  If you are using [Auth](https://plaid.com/docs/auth/index.html.md) , you can integrate Identity Match via the [Account Verification Dashboard](https://dashboard.plaid.com/account-verification) . This is a lower-code option that allows you to rely on Plaid Link for checking match scores and handling failed sessions. When enabling Identity in this way, the Identity check will be incorporated into the Link flow. This configuration option can only be used if Auth and Identity are the only required Plaid products you are using in the session. If you need access to other products, use the [standard integration flow](https://plaid.com/docs/identity/index.html.md#integration-overview) . 1. In the [Dashboard](https://dashboard.plaid.com/account-verification) , select your Link customization and enable the "Configure via Dashboard" toggle. 2. Select the settings for Auth you would like to use, then click "Next". 3. Select the rules to use for Identity Match. Typically, the match threshold for each field should be set to a score of 70 or higher. 4. When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) : * Ensure that `identity` is in the `products` array (or `required_if_supported_products` array, if you want to allow customers to link accounts if their bank does not support Identity). * Set the `link_customization_name` to the customization you selected in Step 1 (this is optional if you are using the `default` customization). * Provide the identity data you have about the user, such as their `legal_name`, `phone_number`, `address`, and `email_address`. 5. Launch Link using the Link token. When the user goes through the Link flow, the identity data you supplied in the previous step will be compared to the data retrieved from their linked financial account. If the result based on your configuration is a pass, they will see a success screen. If it is a failure, they will see an error. 6. Watch for the `IDENTITY_MATCH_PASSED` or `IDENTITY_MATCH_FAILED` event from Link to detect the result of Identity Match in the Link flow. You can also view the status of a completed session in the [Dashboard](https://dashboard.plaid.com/account-verification) . If the Identity Match check fails, you will not receive a `HANDOFF` event or `onSuccess` callback, but if you want to proceed with creating an Item anyway, you can obtain the `public_token` by calling [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) . If Identity is enabled via the Account Verification Dashboard, you will be billed for Identity Match as long as Plaid could obtain any Identity data from the Item, even if you did not exchange the `public_token`. If Plaid was unable to obtain any Identity data for the Item, you will not be billed. ```node const request: LinkTokenCreateRequest = { loading_sample: true }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```python request = LinkTokenCreateRequest( loading_sample=True ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "loading_sample": true }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { loading_sample: true } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .loadingSample(true); Response response = client .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```go request := plaid.NewLinkTokenCreateRequest( "Sample App App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetLoadingSample(true) linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := linkTokenCreateResp.GetLinkToken(); ``` #### Testing Identity  Identity can be tested in Sandbox against test data. Plaid provides a [GitHub repo](https://github.com/plaid/sandbox-custom-users/) with test data for testing Identity in Sandbox, helping you test configuration options beyond those offered by the default Sandbox user. For more information on configuring custom Sandbox data, see [Configuring the custom user account](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuring-the-custom-user-account) . [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) can be tested in Sandbox using custom user accounts as described above. Note that it is not recommended to send real user data or PII in the Sandbox environment for use with [/identity/match](https://plaid.com/docs/api/products/identity/index.html.md#identitymatch) , as Sandbox is meant for testing purposes. For details on testing Identity Match with Same Day Micro-deposits, see [Testing Same-Day Microdeposits](https://plaid.com/docs/auth/coverage/testing/index.html.md#testing-same-day-micro-deposits) . When testing Identity Match using the default `user_good` custom Sandbox user, you can expect the following identity data to be used for matching against: ```bash Alberta Bobbeth Charleson 2992 Cameron Rd. Malakoff, NY 14236 Phone: +1-111-222-3333 Email: accountholder0@example.com ``` #### Identity Document Upload  The [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) add-on can be used to verify account ownership based on a bank statement uploaded by an end user. This feature is intended primarily for use with Items created via loginless Auth flows, such as Same-Day Micro-deposits, Instant Micro-deposits, or Database Insights. For more details, see [Identity Document Upload](https://plaid.com/docs/identity/identity-document-upload/index.html.md) . #### Sample app tutorial and code  For a real-life example of an app that incorporates Identity, see the Node-based [Plaid Pattern Account Funding](https://github.com/plaid/pattern-account-funding) sample app. Pattern Account Funding is a sample account funding app that fetches Identity data in order to verify identity prior to a funds transfer. The Identity code can be found in [items.js](https://github.com/plaid/pattern-account-funding/blob/master/server/routes/items.js#L81-L116) . For a tutorial walkthrough of creating a similar app, see [Account funding tutorial](https://github.com/plaid/account-funding-tutorial) . #### Identity pricing  Identity is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) , meaning you will be billed once for each Item with Identity added to it. Identity Match is billed on [a per-request flat-fee basis](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) . #### Identity availability by country  Identity and Identity Match are available in all supported countries (US, Canada, and Europe, including the UK). In Canada, Identity Match cannot be requested via the Production access form and is available via a Growth or Custom plan only. To request access to Identity Match in Canada, contact your account manager or [sales](https://plaid.com/contact/) . #### Next steps  To get started building with Identity, see [Add Identity to your App](https://plaid.com/docs/identity/add-to-app/index.html.md) . If you're ready to launch to Production, see the Launch Center. #### Launch Center  See next steps to launch in Production [Launch](https://dashboard.plaid.com/developers/launch-center) --- # Income - Add Income to your app | Plaid Docs Add Income to your app  ======================= #### Use Income to fetch income information about your users  This guide will walk you through how to use [Income](https://plaid.com/docs/api/products/income/index.html.md) to retrieve information about your users' current sources of income. This is a basic quickstart guide that does not cover all features of the Income product. For more complete information about Income endpoints and capabilities, see the individual product pages for [Bank Income](https://plaid.com/docs/income/bank-income/index.html.md) , [Document Income](https://plaid.com/docs/income/document-income/index.html.md) , and [Payroll Income](https://plaid.com/docs/income/payroll-income/index.html.md) . #### Get Plaid API keys and complete application and company profile  If you don't already have one, [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard. You also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard if you wish to retrieve real data in Production. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) , and must be completed before connecting to certain institutions. #### Install and initialize Plaid libraries  You can use our official server-side client libraries to connect to the Plaid API from your application: ```node // Install via npm npm install --save plaid ``` ```bash ## Not applicable with curl calls ``` ```ruby # Available as a gem gem install plaid ``` ```java /* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ implementation "com.plaid:plaid-java:{VERSION}" /* For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ com.plaid plaid-java {VERSION} ``` ```python # Install through pip, only supports Python 3 pip install --upgrade plaid-python ``` ```go go get github.com/plaid/plaid-go ``` After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls. ```node // Using Express const express = require('express'); const app = express(); app.use(express.json()); const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const client = new PlaidApi(configuration); ``` ```bash ## Not applicable with curl calls ``` ```ruby require 'sinatra' require 'plaid' set :port, ENV['APP_PORT'] || 8000 configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) ``` ```java import java.net.*; import java.io.*; import retrofit2.Response; import java.util.Arrays; import com.sun.net.httpserver.*; import com.plaid.client.ApiClient; import com.plaid.client.request.PlaidApi; public class PlaidExample { private static final String CLIENT_ID = System.getenv("PLAID_CLIENT_ID"); private static final String SECRET = System.getenv("PLAID_SECRET"); public static void main(String[] args) { HttpServer server = HttpServer.create( new InetSocketAddress("localhost", 8000), 0); server.createContext("/create_link_token", new GetLinkToken()); server.setExecutor(null); server.start(); } // Additional server code goes here } ``` ```python import plaid from plaid.api import plaid_api from flask import Flask from flask import render_template from flask import request from flask import jsonify app = Flask(name) configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Additional server code goes here if __name__ == "__main__": app.run(port=8000) ``` ```go import ( "context" "net/http" "os" "github.com/gin-gonic/gin" "github.com/plaid/plaid-go/v3/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) func main() { r := gin.Default() // Server endpoints would be declared here // e.g. r.POST("/create_link_token", createLinkToken) r.POST("/create_link_token", createLinkToken) err := r.Run(":8000") if err != nil { panic("unable to start server") } } ``` #### Create a User Token  Unlike many other Plaid products, where you start by creating `Items` to represent user connections with individual banks, with Income you first start by creating a `user_token` that represents an individual user. As you add various sources of income, those will all be associated with this single `user_token`, which allows you to receive consolidated income from different sources by requesting an income report for that `user_token`. To create a `user_token`, make a call to the [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) endpoint. This endpoint requires a unique `client_user_id` value to represent the current user. Typically, this value is the same identifier you're using in your own application to represent the currently signed-in user. This call will return a randomly-generated string for the `user_token` as well as a separate user ID that Plaid includes in webhooks to represent this user. You can only create one `user_token` per `client_user_id`. If you try to create a `user_token` with a `client_user_id` that you have previously sent to Plaid, you will receive an error. Depending on your application, you might wish to create this `user_token` as soon as your user creates an account, or right before they begin the process of confirming their income data with you. server.js ```javascript const { IdentityGetRequest } = require('plaid'); // Pull Identity data for an Item const request: IdentityGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.identityGet(request); const identities = response.data.accounts.flatMap( (account) => account.owners, ); } catch (error) { // handle error } // The userId here represents the user's internal user ID with your // application const createUserToken = async (userId) => { const response = await plaidClient.userCreate({ client_user_id: userId, }); const newUserToken = response.data.user_token; const userIdForWebhooks = response.data.user_id; await updateUserRecordWithIncomeInfo(userId, newUserToken, userIdForWebhooks); }; ``` #### Decide what income verification method(s) you want to support  Income supports three different ways that a user can verify their sources of income. * _Payroll Income_ allows Plaid to retrieve information such as recent pay stubs and W-2 forms directly from the user's payroll provider. This tends to provide the most comprehensive data, but is dependent upon the user being able to sign in with their payroll provider. * _Document Income_ allows the user to upload images of income-related documents (such as pay stubs and W-2 forms), which Plaid can scan and interpret for you. * _Bank Income_ allows the user to connect with their bank to identify deposits that represent sources of income. Depending on which methods you want to support (and it's perfectly acceptable to support all three), you will need to implement slightly different processes. While you can collect Payroll and Document Income in the same Link flow, you cannot collect Payroll or Document Income in the same Link flow as Bank Income. ### Fetching Payroll or Document Income data  The process for implementing Payroll and Document Income is very similar, so we'll cover these two scenarios next. #### Create a Link token for Payroll or Document Income  Plaid Link is a drop-in module that provides a secure, elegant UI flow to guide your users through the process of connecting Plaid with their financial institutions. With Income, Link can help your user search for and connect to their payroll provider as well as assist them in uploading documents. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the appropriate section in the [Link documentation](https://plaid.com/docs/link/index.html.md) . Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, single-use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, initialize Link with the `link_token` that you just created. When calling the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint, you'll include an object telling Plaid about your application as well as how to customize the Link experience. When creating a `link_token` for Payroll or Document Income, there are a few extra values you'll need to supply in this object: * You will need to pass in the `user_token` that you created earlier. * You can only list `"income_verification"` in the list of products * You will need to create an object with `income_source_types` set to `["payroll"]` and pass that as the value for `income_verification` Note that in the code sample below, in addition to passing in a `user_token`, we are also passing in the signed in user's ID as the `user.client_user_id` value. These are fundamentally different user IDs used for different purposes. The `user.client_user_id` value is primarily used for logging purposes and allows you to search for activity in the Plaid Dashboard based on the user ID. While its value is most likely the same user ID that you passed in when creating the `user_token` above, they are otherwise unrelated. server.js ```javascript // Using Express app.post('/api/create_link_token_for_payroll_income', async function ( request, response, ) { // Get the client_user_id by searching for the current user. const clientUserId = await GetSignedInUserId(); // Get the Plaid user token that we stored in an earlier step const userToken = await GetPlaidTokenForUser(); const configs = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['income_verification'], user_token: userToken, income_verification: { income_source_types: ['payroll'], }, language: 'en', webhook: 'https://webhook.example.com', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(configs); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` By default, a `link_token` created this way will allow the user to collect income information using both the Payroll and Document methods. However, in some cases you might want to permit the user to only use one of these methods. To do that, you can specify the `flow_types`, as in the example below. ```javascript income_verification: { income_source_types: ["payroll"], payroll_income: { flow_types: ["payroll_digital_income"] }, }, ``` ##### Install the Link library  You need to install the Link JavaScript library from Plaid in order to use Link in your web application. index.html ```html Connect a bank ``` ##### Configure the client-side Link handler  To run Link, you'll first need to retrieve the `link_token` from the server using the call to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) described above. Then, call `Plaid.create()`, passing along that token alongside other callbacks you might want to define. This will return a handler that has an `open` method. Call that method to open up the Link UI and start the connection process. app.js ```javascript const linkHandler = Plaid.create({ token: (await $.post('/api/create_link_token_for_payroll_income')).link_token, onSuccess: (public_token, metadata) => { // Typically, you'd exchange the public_token for an access token. // While you can still do that here, it's not strictly necessary. }, onExit: (err, metadata) => { // Optionally capture when your user exited the Link flow. // Storing this information can be helpful for support. }, onEvent: (eventName, metadata) => { // Optionally capture Link flow events, streamed through // this callback as your users connect an Item to Plaid. }, }); linkHandler.open(); ``` If you've had experience with other Plaid products, you're probably used to taking the `public_token` received from Link and exchanging it on your server for a persistent `access_token`. However, because Payroll and Document Income are fetched once (and don't require persistent connections with your user's bank), and all of your reports are associated with the user's `user_token`, there's no need to retrieve or store an `access_token` in this case. #### Listen for webhooks  After a user has finished using Link, it may take some time before Plaid has the user's income information available for you to download. In the case of Payroll Income, this typically takes a few seconds. For Document Income, this may take several minutes. Listen for the `INCOME: INCOME_VERIFICATION` webhook to know when this user's data is ready. webhookServer.js ```javascript app.post('/server/receive_webhook', async (req, res, next) => { const product = req.body.webhook_type; const code = req.body.webhook_code; if (product === 'INCOME' && code === 'INCOME_VERIFICATION') { const plaidUserId = req.body.user_id; const verificationStatus = req.body.verification_status; if (verificationStatus === 'VERIFICATION_STATUS_PROCESSING_COMPLETE') { await retrieveIncomeDataForUser(plaidUserId); } else { // Handle other cases } } // Handle other types of webhooks }); ``` The `user_id` value included in this webhook is the same `user_id` that was returned by Plaid when you first created a `user_token` for this user. #### Fetch income data  Now that Plaid has confirmed it has finished processing this user's data, you can fetch the data by making a call to the [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) endpoint. Pass in the `user_token`, and Plaid will return all Payroll and Document Income sources associated with that token. server.js ```javascript try { const response = await plaidClient.creditPayrollIncomeGet({ user_token: userToken, }); const incomeData = response.data; // Do something interesting with the income data here. } catch (error) { // Handle error } ``` This call will typically return an array of `items`, each of which represents a connection with a payroll provider. These `items`, in turn, contain one or more `payroll_income` objects that contain detailed payroll information for the user. This can include individual pay stubs (with a full breakdown of gross pay, deductions, net pay, and more), as well as W-2 forms and all of their information. See the [sample response object](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) in the documentation for a full example of what this response might look like. You can distinguish between income that was retrieved through Payroll Income and income that was retrieved through Document Income by looking for an `account_id` value on the `payroll_income` object. If the data was retrieved through scanning user documents, this value will be null. ### Fetching Bank Income data  As an alternative to downloading income data from the user's payroll provider or W-2 forms, Plaid can also find income data in the user's bank account. Plaid will look for deposits that might be sources of income and ask the user to identify which deposits represent income that they wish to share with your application. #### Create a Link token for Bank Income  Creating a `link_token` for Bank Income is similar to the process for creating a `link_token` for Payroll or Document Income. The main differences are: * While you still must include `"income_verification"` as a product, you are allowed to combine this product with other products that you might want to use with this financial institution. * Your `income_source_types` must be set to `["bank"]`. * Your `income_verification` object must also include a `bank_income` object, where you have set the value of `days_requested`. This is the number of days back that Plaid will search for regularly occurring deposits. The value of `days_requested` should a large enough number that you find all relevant deposits, but not so large that the user gets tired waiting for Plaid to retrieve all the relevant data. We recommend 120 days as good balance between the two. server.js ```javascript app.post('/api/create_link_token_for_bank_income', async function ( request, response, ) { // Get the client_user_id by searching for the current user. const clientUserId = await GetSignedInUserId(); // Get the Plaid user token that we stored in an earlier step const userToken = await GetPlaidTokenForUser(); const configs = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['income_verification', 'transactions', 'assets'], user_token: userToken, income_verification: { income_source_types: ['bank'], bank_income: { days_requested: 120 }, }, language: 'en', webhook: 'https://webhook.example.com', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(configs); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ##### Install the Link library  As described earlier, you need to install the Link JavaScript library from Plaid to use Link in your web application. index.html ```html Connect a bank ``` ##### Configure the client-side Link handler  Retrieve the `link_token` from the server, then call `Plaid.create()`, passing along the `link_token` alongside other callbacks you might want to define. This will return a handler that has an `open` method, which you can call to start the Link process. This is similar to the process described above, but with Bank Income you will probably want to keep the `public_token` and exchange it for an `access_token`, as described in the next step. app.js ```javascript const linkHandler = Plaid.create({ token: (await $.post('/api/create_link_token_for_bank_income')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token to your app server. $.post('/exchange_public_token', { public_token: public_token, }); }, onExit: (err, metadata) => { // Optionally capture when your user exited the Link flow. // Storing this information can be helpful for support. }, onEvent: (eventName, metadata) => { // Optionally capture Link flow events, streamed through // this callback as your users connect an Item to Plaid. }, }); linkHandler.open(); ``` ##### Retrieve metadata about the Link session  Call [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) in your server after receiving `onSuccess`, passing in the `link_token`. If you enabled [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , you should instead wait for the [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) webhook rather than the `onSuccess` frontend callback, to ensure that the Link flow is complete, and all Items have been linked. For more details, see the [Multi-Item Link docs](https://plaid.com/docs/link/multi-item-link/index.html.md) . Previously, customers were instructed to call [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) to obtain the public token. While this flow is still supported, all customers are encouraged to use the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint to obtain the public token instead, for improved consistency with other Plaid products and flows. server.js ```javascript try { const response = await plaidClient.linkTokenGet({ link_token: LinkToken, }); const sessionData = response.data; } catch (error) { // Handle this error } ``` If you are using other Plaid products such as Auth or Balance alongside Bank Income, make sure to capture the `public_token` (or tokens) from the `results.item_add_result` field and exchange it for an `access_token`. #### Get a persistent access token (for other products)  For the purpose of retrieving income data, you don't necessarily need an `access_token`. Plaid will retrieve the income data for you, and then that data will be associated with the `user_token` that you created when first configuring Link. However, if you are using any other product with this financial institution (such as Transactions, Balance, or Assets), you will need to exchange your `public_token` for an `access_token` and `item_id`. The `access_token` lets you make authenticated calls to these other products in the Plaid API. Exchanging a `public_token` for an `access_token` is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from the server-side handler. Store the `access_token` and `item_id` that get returned in a secure server-side location. Never store this information on the client. ```node app.post('/api/exchange_public_token', async function ( request, response, next, ) { const publicToken = request.body.public_token; try { const tokenResponse = await client.itemPublicTokenExchange({ public_token: publicToken, }); // These values should be saved to a persistent database and // associated with the currently signed-in user const accessToken = tokenResponse.data.access_token; const itemID = tokenResponse.data.item_id; response.json({ public_token_exchange: 'complete' }); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-12345678-abcd-1234-abcd-1234567890ab" }' ``` ```ruby access_token = nil post '/api/exchange_public_token' do request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: params["public_token"] } ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response.access_token item_id = response.item_id content_type :json {public_token_exchange: "complete"}.to_json end ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; public class PlaidExample { ... static class GetAccessToken implements HttpHandler { private static PlaidClient plaidClient; private String publicToken; private String accessToken; private String itemId; public void handle(HttpExchange t) throws IOException { // Simplified pseudo-code for obtaining public_token InputStream is = t.getRequestBody(); publicToken = is.publicToken(); // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange public_token for an access_token ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response response = plaidClient .itemPublicTokenExchange(request) .execute(); // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken = response.body().getAccessToken(); itemId = response.body().getItemId(); String message = "{\"public_token_exchange\": \"complete\"}"; return Response .status(Response.Status.OK) .entity(message) .type(MediaType.APPLICATION_JSON) } } } ``` ```python access_token = None item_id = None @app.route('/exchange_public_token', methods=['POST']) def exchange_public_token(): global access_token public_token = request.form['public_token'] request = ItemPublicTokenExchangeRequest( public_token=public_token ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response['access_token'] item_id = response['item_id'] return jsonify({'public_token_exchange': 'complete'}) ``` ```go func getAccessToken(c *gin.Context) { ctx := context.Background() publicToken := c.PostForm("public_token") // exchange the public_token for an access_token exchangePublicTokenReq := plaid.NewItemPublicTokenExchangeRequest(publicToken) exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *exchangePublicTokenReq, ).Execute() // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken := exchangePublicTokenResp.GetAccessToken() itemID := exchangePublicTokenResp.GetItemId() c.JSON(http.StatusOK, gin.H{"public_token_exchange": "complete"}) } ``` #### Fetch income data  You can fetch income data by calling the [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) endpoint using the Plaid client library, passing in the `user_token` you created earlier. Note that, similar to Document or Payroll Income, this data is static -- it is a snapshot of the user's income data that was retrieved by Plaid when the user ran Link. It does not update or change over time. By default, Plaid will only return the most recent report in its response. However, you might want to retrieve more than one report if your user has intentionally run Link multiple times. You can do this by passing an `options` object with a `count` value set to an integer. server.js ```javascript try { const response = await plaidClient.creditBankIncomeGet({ user_token: userRecord[FIELD_USER_TOKEN], options: { count: 3, }, }); const bankIncomeData = response.data; } catch (error) { // Handle this error } ``` This call typically returns a `bank_income` array, which consists of a number of different objects that represent the report generated when the user ran Link. These individual reports contain an `items` array, which in turn contains one or more objects that represent the financial institutions associated with this report. These objects contain a `bank_income_accounts` array of objects, which gives you information about the individual accounts, as well as a `bank_income_sources` array of objects, which in turn contains the total amount of income reported, along with historical transactions about that income. Each report also contains a `bank_income_summary` object, that summarizes the total bank income identified across all items in this report. #### Example code  For an example of an app that incorporates Document, Payroll and Bank Income, see the React and Node-based [Income Sample app](https://github.com/plaid/income-sample) . The Income Sample app is an application that uses Income and Liability data to help determine whether the user can qualify for financing on a pre-owned hoverboard. It supports the use of all three types of income data. #### Next steps  If you're ready to launch to Production, see the Launch checklist. #### Launch checklist  Recommended steps to take before launching in Production [Launch](https://plaid.com/docs/launch-checklist/index.html.md) --- # Income - Bank Income | Plaid Docs Bank Income  ============ #### Learn about Bank Income features and implementation  Get started with Bank Income [API Reference](https://plaid.com/docs/api/products/income/index.html.md) [Quickstart](https://github.com/plaid/income-sample) [Income Verification Demo](https://plaid.coastdemo.com/share/66fb0a180582208ffa82103e?zoom=100) #### Overview  Bank Income allows you to instantly retrieve net income information from a user-connected bank account, supporting both irregular or gig income and W-2 income. Data available includes a breakdown of income streams to the account, as well as recent and historical income. [Prefer to learn by watching? Get an overview of how Income works in just 3 minutes!](https://www.youtube.com/watch?v=Hc-MpibSxJE) For all new integrations supporting end users based in the US, Plaid recommends the use of [Consumer Report](https://plaid.com/docs/check/index.html.md) instead of Bank Income. Consumer Report's income solution provides FCRA compliant insights and bundles income calculations (historical average income, forecasted income, predicted next payment date) in a single report. For more information, see [Plaid Check Consumer Report](https://plaid.com/docs/check/index.html.md) . #### No-code Income integration with the Credit Dashboard  Bank Income can be used as part of a no-code integration flow. This integration mode is available only when using Income alongside Assets. For more details, see the [Assets no-code integration guide](https://plaid.com/docs/assets/index.html.md#no-code-integration-with-the-credit-dashboard) . #### Integration process  New customers integrating with Bank Income after December 10, 2025 must request access to user tokens by contacting sales or their account manager, or filing a support ticket via the Dashboard. If access is not requested, [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) will not generate a user token, and will generate only a `user_id` instead. Later in Q1 2026, Plaid will add an integration option for Income that does not require user tokens. For details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . 1. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) to create a `user_token` that will represent the end user interacting with your application. This step will only need to be done once per end user. If you are using multiple Income types, do not repeat this step when switching to a different Income type. If you do not receive a `user_token` when calling [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) , contact your account manager or file a support ticket to request access. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis/index.html.md) . 2. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following: * For `user_token`, provide the `user_token` from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . * For `products`, use `["income_verification"]`. You can also specify additional products. For more details, see [Using Bank Income with other products](https://plaid.com/docs/income/bank-income/index.html.md#using-bank-income-with-other-products) . * For `income_verification.income_source_types`, use `bank`. * Set `income_verification.bank_income.days_requested` to the desired number of days. * Provide a `webhook` URI with the endpoint where you will receive Plaid webhooks. 3. On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . 4. Open Link in your web or mobile client and listen to the `onSuccess` and `onExit` callbacks, which will fire once the user has finished or exited the Link session. 5. If you are using other Plaid products such as Auth or Balance alongside Bank Income, call [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) and make sure to capture each `public_token` from the `results.item_add_results` array. Exchange each `public_token` for an `access_token` using [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . For more details on token exchange, see the [Token exchange flow](https://plaid.com/docs/api/items/index.html.md#token-exchange-flow) . 6. To retrieve data, call [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) with the `user_token`. #### Multi-Item sessions  Many users get income deposited into multiple institutions. To help capture a user's full income profile, you can allow your users to link multiple accounts within the same link session on web integrations. (An image of "Select bank, enter credentials, choose income transactions, and review income in Plaid's bank income flow.") Bank Income Multi Item Link flow (some panes excluded) To enable this flow, see [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) . The previous Income-specific flow, which used the `income_verification.bank_income.enable_multiple_items` setting in [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and obtained public tokens from the [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) endpoint, has been deprecated and replaced with a generic Multi-Item Link flow that supports all Plaid and Plaid Check products. #### Using Bank Income with other products  Bank Income Items are fully compatible with other Plaid Item-based products, including Auth, Transactions, Balance, and Assets. When initializing Link, if you plan to use Bank Income and Assets in the same session, it is recommended to put both `income_verification` and `assets` in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) `products` array. If you plan to use Bank Income with Transactions, you should not put `transactions` in the `products` array, as this may increase latency. For more details, see [Choosing how to initialize Link](https://plaid.com/docs/link/initializing-products/index.html.md) . To capture an `access_token` for use with other products, call [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) after receiving the `onExit` or `onSuccess` callback from Link. This endpoint will return all `public_token`s for every Item linked to a given `user_token`. For details on the API schema, see the [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) documentation. You can then exchange these `public_tokens` for `access_tokens` using [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . #### Verifying Bank Income for existing Items  If your user has already connected their depository bank account to your application for a different product, you can add Bank Income to the existing Item via [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . To do so, in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request described above, populate the `access_token` field with the access token for the Item. If the user connected their account less than two years ago, they can bypass the Link credentials pane and complete just the Income Verification step. Otherwise, they will be prompted to complete the full Plaid Bank Income Link flow. #### Institution coverage  To determine whether an institution supports Bank Income, you can use the Dashboard status page (look for "Bank Income") or the [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) endpoint (look for or filter by the `income_verification` product). The `income` product returned by these surfaces represents a legacy product and does not indicate coverage for Bank Income. #### Testing Bank Income  In Sandbox, you can use the user `user_bank_income` with the password `{}`. The basic [Sandbox credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#sandbox-simple-test-credentials) (`user_good`/`pass_good`) will not return data when used to test Bank Income. Plaid also has additional test users for scenarios such as joint accounts, bonus income, and different levels of creditworthiness: for details, see [Credit and Income testing credentials](https://plaid.com/docs/sandbox/test-credentials/index.html.md#credit-and-income-testing-credentials) . When using special Sandbox test credentials (such as `user_bank_income` / `{}`), use the [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) flow or a non-OAuth test institution, such as First Platypus Bank (`ins_109508`). Special test credentials may be ignored when using the Sandbox Link OAuth flow. If you'd like to test Bank Income with custom data, Plaid provides several [test JSON configuration objects](https://github.com/plaid/sandbox-custom-users/tree/main/income) . To load this data into Sandbox, copy and paste the JSON into a new custom user via the [Sandbox Users pane](https://dashboard.plaid.com/developers/sandbox) in the Dashboard. [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) can optionally be tested in Sandbox without using Link. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and pass the returned `user_token` to [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) . [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) must be called with the following request body: /sandbox\_public/token/create request for Bank Income testing ```bash { "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "institution_id": "ins_20", //any valid institution id is fine "initial_products": ["income_verification"], "user_token": "user-token-goes-here", //use the user_token from the `/user/create` call made earlier "options": { "override_username": "user_bank_income", //or other test user from Credit and Income testing credentials "override_password": "{}", "income_verification": { "income_source_types": ["bank"], "bank_income": { "days_requested": 120 //any number of days under 730 is valid } }, } } ``` After calling [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) , call [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) using the same `user_token`. The output of [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) will not be used, but calling it initializes the user token for testing. #### Bank Income pricing  Bank Income is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) . Bank Income Refresh is billed on a [per-request fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) . #### Next steps  If you're ready to launch to Production, see the Launch checklist. #### Launch Center  See next steps to launch in Production [Launch](https://dashboard.plaid.com/developers/launch-center) --- # Income - Document Income | Plaid Docs Document Income  ================ #### Learn about Document Income features and implementation  Get started with Document Income [API Reference](https://plaid.com/docs/api/products/income/index.html.md) [Quickstart](https://github.com/plaid/income-sample) #### Overview  Document Income allows you to retrieve gross and/or net income information via user-uploaded documents such as a pay stub, bank statement, W-2, or 1099 form. [Prefer to learn by watching? Get an overview of how Income works in just 3 minutes!](https://www.youtube.com/watch?v=Hc-MpibSxJE) #### Integration process  1. (Optional) Update your [Link customization](https://dashboard.plaid.com/link/manualVerificationOfIncomeUpload) in the Dashboard to configure which types of documents a user can upload to verify their income. By default, if you do not change this setting, only pay stubs are accepted. 2. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) to create a `user_token` that will represent the end user interacting with your application. This step will only need to be done once per end user. If you are using multiple Income types, do not repeat this step when switching to a different Income type. 3. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following: * For `user_token`, provide the `user_token` from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . * For `products`, use `["income_verification"]`. Document Income cannot be used in the same Link session as any other Plaid products, except for Payroll Income. * For `income_verification.income_source_types`, use `payroll`. * (Optional) If you are only using Document Income and do not want customers to use Payroll Income, for `income_verification.payroll_income.flow_types`, use `["payroll_document_income"]`. * Provide a `webhook` URI with the endpoint where you will receive Plaid webhooks. * If using Fraud Risk, set `income_verification.payroll_income.parsing_config` to either `['risk_signals']` or `['risk_signals', 'ocr']`. For more details, see [Fraud Risk detection](https://plaid.com/docs/income/document-income/index.html.md#fraud-risk-detection) . 4. On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see [Link](https://plaid.com/docs/link/index.html.md) . 5. Open Link in your web or mobile client and listen to the `onSuccess` and `onExit` callbacks, which will fire once the user has finished or exited the Link session. 6. If using Fraud Risk, wait for the [INCOME: INCOME\_VERIFICATION\_RISK\_SIGNALS](https://plaid.com/docs/api/products/income/index.html.md#income_verification_risk_signals) webhook, then call [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) . * If the document requires manual review, call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) to get a URI where the user's original documents can be downloaded. 7. If using Document Parsing, wait for the [INCOME: INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook, then call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) and/or [/credit/bank\_statements/uploads/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_statementsuploadsget) to obtain parsed income details. You can use [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) to see what document types were uploaded, which will determine which of the two endpoints to call. For details, see [Document Parsing](https://plaid.com/docs/income/document-income/index.html.md#document-parsing) . #### Fraud risk detection  To detect potential document fraud or document tampering during the Document Income flow, you can use the optional Fraud Risk feature. Fraud Risk's AI-powered analysis scans for over two dozen different fraud signals within categories such as: visual evidence of tampering, suspicious metadata, inconsistent contents, and similarity to known fraudulent documents. If your account is not enabled for this feature, contact sales or your Plaid account manager to request access. To enable Fraud Risk: 1. When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , set the `income_verification.payroll_income.parsing_config` array to include `'risk_signals'`. By default, this will disable [Document Parsing](https://plaid.com/docs/income/document-income/index.html.md#document-parsing) ; to keep it enabled, include `'ocr'` in the array as well. 2. When the risk analysis has been completed, you will receive an [INCOME\_VERIFICATION\_RISK\_SIGNALS](https://plaid.com/docs/api/products/income/index.html.md#income_verification_risk_signals) webhook. This webhook may take up to 45 minutes to fire. 3. Once the webhook has been received, call the [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) endpoint. [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) will return a risk score for each document, as well as a detailed set of reasons for any potential risk. You can automatically reject documents with a high risk score, automatically accept documents with a low risk score, and manually review documents in between. We suggest starting with a threshold of 80 for auto-rejection and 20 for auto-acceptance. As you gather more data points on typical risk scores for your use case, you can tune these parameters to reduce the number of documents undergoing manual review. To obtain a copy of the original document for manual review, call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) and use the `document_metadata.download_url`. To enable Fraud Risk on a verification where the Link flow has already been completed, use the [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) endpoint. #### Document Parsing  Document Parsing is an optional feature that allows you to obtain a JSON representation of an uploaded document. If your account is not enabled for this feature, contact sales or your Plaid account manager to request access. To enable Document Parsing: 1. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) as normal, then launch Link and have the user go through the Link flow. You do not need to specify a `parsing_config` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , as Document Parsing will be enabled by default if this field is omitted. However, if this field is supplied (for example, to enable Fraud Risk), it must include `ocr` to enable Document Parsing. 2. To see which file types a user uploaded, use [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) . The `document_income_results` field will show how many of each filetype were uploaded. 3. Wait for document parsing to complete, which will be indicated by the [INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook. This webhook may take up to 45 minutes to fire. 4. Once the webhook has been received, to obtain parsed JSON data from a pay stub, W-2, or 1099, use [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . To obtain parsed JSON data from a bank statement, use [/credit/bank\_statements/uploads/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_statementsuploadsget) . To enable Document Parsing on a verification where the Link flow has already been completed, use the [/credit/payroll\_income/parsing\_config/update](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeparsing_configupdate) endpoint. #### Downloading original documents  To download the original user-uploaded documents, use the `document_metadata.download_url` returned by [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . #### Customizing document uploads  To configure which documents your users can upload, create a [Link customization in the Dashboard](https://dashboard.plaid.com/link) . You must update this setting in order to accept documents other than pay stubs. Bank statements are only supported with a custom contract. If you are not contracted for bank statements, do not enable bank statement uploads in your Link customization, as it will cause your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) calls to fail. To request access to bank statement uploads, contact sales or your account manager. ##### Supported document types  * Pay stubs * Bank statements (requires custom contract) * W-2 * 1099-K * 1099-MISC Each uploaded file must contain exactly one instance of the document type being submitted. For example, if uploading a pay stub, the file should contain a single pay stub — not multiple pay stubs combined into one file. ##### Supported file types  * PDF * PNG * JPEG * GIF * BMP * TIFF For more details, see [Document upload settings](https://plaid.com/docs/link/customization/index.html.md#document-income-only-document-upload-settings) . #### Testing Document Income  In the Sandbox environment, when testing Document Income, by default, the contents of the actual document will not be processed and Sandbox will instead use pre-populated test data. You can customize the response you get by uploading JSON files with a custom configuration schema in the Link flow. Each JSON file will represent one document in the response and can include customizations for: * Either a paystub or a W-2 * Risk signals * OCR parsing status * Risk signals status The customization schema for each document and risk signals is very similar to the objects in the responses from [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) and [/credit/payroll\_income/risk\_signals/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerisk_signalsget) . Example JSON files that you can adapt can be found in the [Custom Sandbox User GitHub repo](https://github.com/plaid/sandbox-custom-users/tree/main/income/document_income) . #### Document Income pricing  Document Income is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) . The fee depends on the number and type of documents processed and which processing options are enabled (i.e. fraud risk, document parsing, or both). To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) . #### Next steps  If you're ready to launch to Production, see the Launch checklist. #### Launch Center  See next steps to launch in Production [Launch](https://dashboard.plaid.com/developers/launch-center) --- # Income - Introduction to Income | Plaid Docs Introduction to Income   ======================== #### Optimize your income verification process with document, payroll, and bank-based Income verification  Get started with Income [API Reference](https://plaid.com/docs/api/products/income/index.html.md) [Quickstart](https://github.com/plaid/income-sample) [Demo](https://plaid.coastdemo.com/share/66fb0a180582208ffa82103e?zoom=100) #### Overview  Most new customers should use the [Consumer Report Income solution](https://plaid.com/docs/check/index.html.md) instead of Income. Consumer Report includes an FCRA-compliant solution providing details on over a dozen categorized income streams along with ready-made, model-driven attributes like historical gross and net income to streamline debt-to-income calculations and income verification. It also provides details like forecasted income, employer name, income frequency, and predicted next payment date. Income is currently recommended only for use cases not supported by Consumer Report, such as underwriting outside the US, or Payroll or Document Income based flows. Plaid Income (US, CA, and UK only) helps you verify anyone's income and employment in seconds, facilitating an improved decisioning and underwriting process. Depending on the Income product you choose, you can request information such as pay stub data, income streams, and historical income. You can enable multiple different methods of income verification, then use the appropriate one for your situation. For example, you might enable Bank Income and also provide Document Income as a fallback for customers who prefer not to link their bank account or don't bank with a Plaid-supported institution. You can verify a user's income via three products: [Document Income:](https://plaid.com/docs/income/document-income/index.html.md) Retrieve gross and/or net income information via user-uploaded documents such as a pay stub, bank statement, W-2, or 1099 form. [Payroll Income (US only):](https://plaid.com/docs/income/payroll-income/index.html.md) Instantly retrieve employment and gross income information, including the information available on a pay stub, from a user-connected payroll account. Supports approximately 80% of the US workforce, including gig income workers. [Bank Income:](https://plaid.com/docs/income/bank-income/index.html.md) Instantly retrieve net income information from a user-connected bank account. Data available includes a breakdown of income streams to the account, as well as recent and historical income. For a fuller view of a borrower's financial situation, Income can also be used with [Assets](https://plaid.com/docs/assets/index.html.md) , which provides user-permissioned asset verification. If you need exact copies of a user's statements, see [Statements](https://plaid.com/docs/statements/index.html.md) . Income is a product of Plaid Inc., which is not a consumer reporting agency. To learn more about products offered by Plaid Consumer Reporting Agency, Inc., (Plaid CRA) see [Plaid Check](https://plaid.com/docs/check/index.html.md) . Income can't be used in the same Link flow as Plaid CRA products. [Prefer to learn by watching? Get an overview of how Income works in just 3 minutes!](https://www.youtube.com/watch?v=Hc-MpibSxJE) #### Next steps  To learn more about integrating Income, see the docs for the Income product you would like to use: [Document Income](https://plaid.com/docs/income/document-income/index.html.md) , [Payroll Income](https://plaid.com/docs/income/payroll-income/index.html.md) , or [Bank Income](https://plaid.com/docs/income/bank-income/index.html.md) . --- # Income - Payroll Income | Plaid Docs Payroll Income  =============== #### Learn about Payroll Income features and implementation  Get started with Payroll Income [API Reference](https://plaid.com/docs/api/products/income/index.html.md) [Quickstart](https://github.com/plaid/income-sample) #### Overview  Payroll Income (US only) allows you to instantly verify employment details and gross income information, including the information available on a pay stub, from a user-connected payroll account. Payroll Income supports approximately 80% of the US workforce, including gig income workers. [Prefer to learn by watching? Get an overview of how Income works in just 3 minutes!](https://www.youtube.com/watch?v=Hc-MpibSxJE) #### Integration process  1. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) to create a `user_token` that will represent the end user interacting with your application. This step will only need to be done once per end user. If you are using multiple Income types, do not repeat this step when switching to a different Income type. 2. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In addition to the required parameters, you will need to provide the following: * For `user_token`, provide the `user_token` from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) . * For `products`, use `["income_verification"]`. Document Income cannot be used in the same Link session as any other Plaid products, except for Payroll Income. * For `income_verification.income_source_types`, use `payroll`. * (Optional) If you are only using Payroll Income and do not want customers to use Document Income, for `income_verification.payroll_income.flow_types`, use `["payroll_digital_income"]`. * Provide a `webhook` URI with the endpoint where you will receive Plaid webhooks. 3. On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see [Link](https://plaid.com/docs/link/index.html.md) . 4. Open Link in your web or mobile client and listen to the `onSuccess` and `onExit` callbacks, which will fire once the user has finished or exited the Link session. 5. Listen for the [INCOME: INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook, which will fire within a few seconds, indicating that the Income data is ready. 6. Call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) for income data, and/or [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) for employment details. #### Payroll Income Refresh  To request access to Payroll Income Refresh, contact your account manager. On-demand Payroll Income Refresh allows you to request updated information from a previously connected payroll account. To trigger a refresh, call [/credit/payroll\_income/refresh](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomerefresh) and specify the `user_token` to refresh. If the refresh is successful, you will receive an [INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook. The next time you call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) , you will receive updated data. If the refresh was not successful, you will receive a [INCOME\_VERIFICATION\_REFRESH\_RECONNECT\_NEEDED](https://plaid.com/docs/api/products/income/index.html.md#income_verification_refresh_reconnect_needed) webhook. To resolve this failure state, send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . The refresh attempt will automatically be retried once the user has completed update mode, and an [INCOME\_VERIFICATION](https://plaid.com/docs/api/products/income/index.html.md#income_verification) webhook will be sent if the retry is successful. #### Download original documents  To download PDF versions of the original payroll documents that were parsed to obtain payroll data, use the `document_metadata.download_url` returned by [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . Not all integrations will return a `download_url`. In cases where an original source cannot be obtained, Plaid can optionally generate a PDF pay stub based on the data obtained. To enable Plaid-generated PDF pay stubs, contact your account manager. [View an example generated pay stub](https://plaid.com/documents/plaid-generated-mock-paystub.pdf) . #### Employment data  Plaid provides employment data via the [/credit/employment/get](https://plaid.com/docs/api/products/income/index.html.md#creditemploymentget) endpoint. If you are on a Pay-as-you-go or Growth plan and want to use this endpoint, contact support to request access. #### Testing Payroll Income  You can test Payroll Income in Sandbox using Link. For best results, select a payment provider that only requests a username, password, and/or SSN. (Good examples are Paycom, Paychex, or Workday.) Use `test-good` as the username, `test` as the password, and `1234` as the last 4 digits of your SSN. You can also see an example Link flow for Payroll Income using the [Plaid Link demo site](https://plaid.com/link-demo/) : select "Payroll and Document Income" from the drop-down and use the credentials above. [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) can optionally be tested in Sandbox without using Link. Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) , pass the returned `user_token` to [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) (use `ins_135842` when creating a public token for Payroll Income in Sandbox), and then call [/credit/payroll\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditpayroll_incomeget) . The output of [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) will not be used, but calling it initializes the user token for testing. Payroll Income does not currently support the use of custom Sandbox data; only the default `user_good` user is compatible with Sandbox Payroll Income. #### Payroll Income pricing  Payroll Income is billed on a [one-time fee model](https://plaid.com/docs/account/billing/index.html.md#one-time-fee) . Payroll Income Refresh is billed on a [per-request fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) . #### Next steps  If you're ready to launch to Production, see the Launch checklist. #### Launch Center  See next steps to launch in Production [Launch](https://dashboard.plaid.com/developers/launch-center) --- # Institutions - European Coverage | Plaid Docs European Bank Coverage Explorer  ================================ #### Search for product coverage by institution  Plaid provides reliable banking connections for businesses expanding across Europe. Unlike other providers relying on aggregation, Plaid delivers direct connections to nearly 2,000 European financial institutions—ensuring faster and more accurate performance. Our coverage explorer below can help you see which Plaid products are supported by different financial institutions. Note that not all products are available in all countries. See [this article](https://support.plaid.com/hc/en-us/articles/27895826947735-What-Plaid-products-are-supported-in-each-country-and-region) for a complete list of what products are supported in each country. This data is updated approximately once a quarter and may not be completely up to date. For the most complete data, use [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) or the [Institution status dashboard](https://dashboard.plaid.com/activity/status/institution) . If you have specific institutional requirements, submit a request via the Plaid Dashboard. If you're interested in US or Canadian banks, see our [US and Canada Bank Coverage Explorer](https://plaid.com/docs/institutions/index.html.md) . Available Markets 🇬🇧 United Kingdom (GB) Solutions All solutions Loading  -------- Last updated: [Download this coverage as CSV](https://plaid.com/documents/eu_institution_coverage.csv) . --- # Institutions - US and Canada Coverage | Plaid Docs US and Canada Bank Coverage Explorer  ===================================== #### Search for product coverage by institution  Plaid supports over 10,000 institutions across the United States and Canada. Our coverage explorer below can help you see which Plaid products are supported by different financial institutions. Note that not all products are available in all countries. See [this article](https://support.plaid.com/hc/en-us/articles/27895826947735-What-Plaid-products-are-supported-in-each-country-and-region) for a complete list of what products are supported in each country. This table is not updated in real time; for the most up to date data, use [/institutions/get](https://plaid.com/docs/api/institutions/index.html.md#institutionsget) or the [Institution status dashboard](https://dashboard.plaid.com/activity/status/institution) . If you're interested in European bank coverage, see our [European Bank Coverage Explorer](https://plaid.com/docs/institutions/europe/index.html.md) . Select Products Auth (Instant) Balance Transactions Only show institutions that support all of these products Select Country 🇺🇸 United States (US) Loading  -------- Last updated: [Download this coverage as CSV](https://plaid.com/documents/us_institution_coverage.csv) . --- # Investments Move - Add Investments Move to your app | Plaid Docs Add Investments Move to your app  ================================= #### Use Investments Move to streamline brokerage-to-brokerage account transfers  In this guide, we'll start from scratch and walk through how to use Investments Move to get the data required to set up an ACATS transfer. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, make sure to initialize Link with the `investments_auth` product; you can then skip ahead to [Fetching Investments Move data](https://plaid.com/docs/investments-move/add-to-app/index.html.md#fetching-investments-move-data) . #### Get Plaid API keys and complete application profile  If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard. You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile must be completed before connecting to certain institutions in Production. #### Install and initialize Plaid libraries  You can use our official server-side client libraries to connect to the Plaid API from your application: ```node // Install via npm npm install --save plaid ``` ```bash ## Not applicable with curl calls ``` ```ruby # Available as a gem gem install plaid ``` ```java /* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ implementation "com.plaid:plaid-java:{VERSION}" /* For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ com.plaid plaid-java {VERSION} ``` ```python # Install through pip, only supports Python 3 pip install --upgrade plaid-python ``` ```go go get github.com/plaid/plaid-go ``` After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls. ```node // Using Express const express = require('express'); const app = express(); app.use(express.json()); const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const client = new PlaidApi(configuration); ``` ```bash ## Not applicable with curl calls ``` ```ruby require 'sinatra' require 'plaid' set :port, ENV['APP_PORT'] || 8000 configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) ``` ```java import java.net.*; import java.io.*; import retrofit2.Response; import java.util.Arrays; import com.sun.net.httpserver.*; import com.plaid.client.ApiClient; import com.plaid.client.request.PlaidApi; public class PlaidExample { private static final String CLIENT_ID = System.getenv("PLAID_CLIENT_ID"); private static final String SECRET = System.getenv("PLAID_SECRET"); public static void main(String[] args) { HttpServer server = HttpServer.create( new InetSocketAddress("localhost", 8000), 0); server.createContext("/create_link_token", new GetLinkToken()); server.setExecutor(null); server.start(); } // Additional server code goes here } ``` ```python import plaid from plaid.api import plaid_api from flask import Flask from flask import render_template from flask import request from flask import jsonify app = Flask(name) configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Additional server code goes here if __name__ == "__main__": app.run(port=8000) ``` ```go import ( "context" "net/http" "os" "github.com/gin-gonic/gin" "github.com/plaid/plaid-go/v3/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) func main() { r := gin.Default() // Server endpoints would be declared here // e.g. r.POST("/create_link_token", createLinkToken) r.POST("/create_link_token", createLinkToken) err := r.Run(":8000") if err != nil { panic("unable to start server") } } ``` #### Create an Item in Link  Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. First, on the client side of your application, you'll need to set up and configure Link. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) . When initializing Link, you will need to specify the products you will be using in the product array. ##### Create a link\_token  ```node app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['investments_auth'], language: 'en', webhook: 'https://webhook.example.com', redirect_uri: 'https://domainname.com/oauth-page.html', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "products": ["investments_auth"], "country_codes": ["US"], "language": "en", "webhook": "https://webhook.example.com", "redirect_uri": "https://domainname.com/oauth-page.html" }' ``` ```ruby post '/api/create_link_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: client_user_id }, client_name: 'Plaid Test App', products: ['investments_auth'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.example.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.Products; import com.plaid.client.model.CountryCode; import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; public class PlaidExample { ... static class GetLinkToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.fromValue("investments_auth"))) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .redirectUri("https://domainname.com/oauth-page.html") .webhook("https://webhook.example.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.link_token_create_request import LinkTokenCreateRequest from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser from plaid.model.products import Products from plaid.model.country_code import CountryCode @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( products=[Products("investments_auth")], client_name="Plaid Test App", country_codes=[CountryCode('US')], redirect_uri='https://domainname.com/oauth-page.html', language='en', webhook='https://webhook.example.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetRedirectUri("https://domainname.com/oauth-page.html") request.SetProducts([]plaid.Products{plaid.PRODUCTS_INVESTMENTS_AUTH}) resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` When using Investments Move, you can also configure options in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call to allow more brokerage accounts to be added, with the tradeoff that Plaid may not be able to verify all of the information. For details, see [Fallback flows](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . ##### Install Link dependency  index.html ```html Connect a bank ``` ##### Configure the client-side Link handler  app.js ```javascript const linkHandler = Plaid.create({ token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token to your app server. $.post('/exchange_public_token', { public_token: public_token, }); }, onExit: (err, metadata) => { // Optionally capture when your user exited the Link flow. // Storing this information can be helpful for support. }, onEvent: (eventName, metadata) => { // Optionally capture Link flow events, streamed through // this callback as your users connect an Item to Plaid. }, }); linkHandler.open(); ``` #### Get a persistent access\_token  Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call. Save the `access_token` and `item_id` in a secure datastore, as they're used to access `Item` data and identify `webhooks`, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it. ```node app.post('/api/exchange_public_token', async function ( request, response, next, ) { const publicToken = request.body.public_token; try { const tokenResponse = await client.itemPublicTokenExchange({ public_token: publicToken, }); // These values should be saved to a persistent database and // associated with the currently signed-in user const accessToken = tokenResponse.data.access_token; const itemID = tokenResponse.data.item_id; response.json({ public_token_exchange: 'complete' }); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-12345678-abcd-1234-abcd-1234567890ab" }' ``` ```ruby access_token = nil post '/api/exchange_public_token' do request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: params["public_token"] } ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response.access_token item_id = response.item_id content_type :json {public_token_exchange: "complete"}.to_json end ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; public class PlaidExample { ... static class GetAccessToken implements HttpHandler { private static PlaidClient plaidClient; private String publicToken; private String accessToken; private String itemId; public void handle(HttpExchange t) throws IOException { // Simplified pseudo-code for obtaining public_token InputStream is = t.getRequestBody(); publicToken = is.publicToken(); // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange public_token for an access_token ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response response = plaidClient .itemPublicTokenExchange(request) .execute(); // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken = response.body().getAccessToken(); itemId = response.body().getItemId(); String message = "{\"public_token_exchange\": \"complete\"}"; return Response .status(Response.Status.OK) .entity(message) .type(MediaType.APPLICATION_JSON) } } } ``` ```python access_token = None item_id = None @app.route('/exchange_public_token', methods=['POST']) def exchange_public_token(): global access_token public_token = request.form['public_token'] request = ItemPublicTokenExchangeRequest( public_token=public_token ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response['access_token'] item_id = response['item_id'] return jsonify({'public_token_exchange': 'complete'}) ``` ```go func getAccessToken(c *gin.Context) { ctx := context.Background() publicToken := c.PostForm("public_token") // exchange the public_token for an access_token exchangePublicTokenReq := plaid.NewItemPublicTokenExchangeRequest(publicToken) exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *exchangePublicTokenReq, ).Execute() // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken := exchangePublicTokenResp.GetAccessToken() itemID := exchangePublicTokenResp.GetItemId() c.JSON(http.StatusOK, gin.H{"public_token_exchange": "complete"}) } ``` #### Fetching Investments Move data  Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. For more detailed information on the schema for account information returned, see [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) . ```bash curl -X POST https://sandbox.plaid.com/investments/auth/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node const request: InvestmentsAuthGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.investmentsAuthGet(request); const investmentsAuthData = response.data; } catch (error) { // handle error } ``` ```python request = InvestmentsAuthGetRequest(access_token=access_token) response = client.investments_auth_get(request) investmentsAuthData = response ``` ```java InvestmentsAuthGetRequest request = new InvestmentsAuthGetRequest() .accessToken(accessToken); Response response = client() .investmentsAuthGet(request) .execute(); ``` ```ruby request = Plaid::InvestmentsAuthGetRequest.new({ access_token: access_token }) response = client.investments_auth_get(request) ``` ```go request := plaid.NewInvestmentsAuthGetRequest(accessToken) resp, _, err := client.PlaidApi.InvestmentsAuthGet(ctx).InvestmentsAuthGetRequest(*request).Execute() ``` The results of the [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) call return the information you need to submit an ACATS transfer, using verified data derived directly from the brokerage. Example response data is below. For more details on the schema of data returned, see the [API Reference](https://plaid.com/docs/api/products/investments-move/index.html.md#investments-auth-get-response-accounts) . Investments move sample response ```json { "accounts": [ { "account_id": "31qEA6LPwGumkA4Z5mGbfyGwr4mL6nSZlQqpZ", "balances": { "available": 43200, "current": 43200, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "4444", "name": "Plaid Money Market", "official_name": "Plaid Platinum Standard 1.85% Interest Money Market", "subtype": "money market", "type": "depository" }, { "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "balances": { "available": null, "current": 320.76, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "5555", "name": "Plaid IRA", "official_name": null, "subtype": "ira", "type": "investment" } ], "holdings": [ { "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "cost_basis": 1, "institution_price": 1, "institution_price_as_of": "2021-05-25", "institution_price_datetime": null, "institution_value": 0.01, "iso_currency_code": "USD", "quantity": 0.01, "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are", "unofficial_currency_code": null, "vested_quantity": 1, "vested_value": 1 }, { "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "cost_basis": 0.01, "institution_price": 0.011, "institution_price_as_of": "2021-05-25", "institution_price_datetime": null, "institution_value": 110, "iso_currency_code": "USD", "quantity": 10000, "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb", "unofficial_currency_code": null, "vested_quantity": null, "vested_value": null }, { "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "cost_basis": 40, "institution_price": 42.15, "institution_price_as_of": "2021-05-25", "institution_price_datetime": null, "institution_value": 210.75, "iso_currency_code": "USD", "quantity": 5, "security_id": "abJamDazkgfvBkVGgnnLUWXoxnomp5up8llg4", "unofficial_currency_code": null, "vested_quantity": 7, "vested_value": 66 } ], "item": { "available_products": [ "assets", "balance", "beacon", "cra_base_report", "cra_income_insights", "signal", "identity", "identity_match", "income", "income_verification", "investments", "processor_identity", "recurring_transactions", "transactions" ], "billed_products": [ "investments_auth" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_115616", "item_id": "7qBnDwLP3aIZkD7NKZ5ysk5X9xVxDWHg65oD5", "products": [ "investments_auth" ], "update_type": "background", "webhook": "https://www.genericwebhookurl.com/webhook" }, "numbers": { "acats": [ { "account": "TR5555", "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "dtc_numbers": [ "1111", "2222", "3333" ] } ] }, "owners": [ { "account_id": "31qEA6LPwGumkA4Z5mGbfyGwr4mL6nSZlQqpZ", "names": [ "Alberta Bobbeth Charleson" ] }, { "account_id": "xlP8npRxwgCj48LQbjxWipkeL3gbyXf64knoy", "names": [ "Alberta Bobbeth Charleson" ] } ], "request_id": "hPCXou4mm9Qwzzu", "securities": [ { "close_price": 0.011, "close_price_as_of": null, "cusip": null, "industry": null, "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "market_identifier_code": null, "name": "Nflx Feb 01'18 $355 Call", "option_contract": null, "proxy_security_id": null, "sector": null, "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb", "sedol": null, "ticker_symbol": "NFLX180201C00355000", "type": "derivative", "unofficial_currency_code": null, "update_datetime": null }, { "close_price": 9.08, "close_price_as_of": "2024-09-09", "cusip": null, "industry": "Investment Trusts or Mutual Funds", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "market_identifier_code": null, "name": "DoubleLine Total Return Bond I", "option_contract": null, "proxy_security_id": null, "sector": "Miscellaneous", "security_id": "AE5rBXra1AuZLE34rkvvIyG8918m3wtRzElnJ", "sedol": "B5ND9B4", "ticker_symbol": "DBLTX", "type": "mutual fund", "unofficial_currency_code": null, "update_datetime": null }, { "close_price": 42.15, "close_price_as_of": null, "cusip": null, "industry": null, "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "market_identifier_code": null, "name": "iShares Inc MSCI Brazil", "option_contract": null, "proxy_security_id": null, "sector": null, "security_id": "abJamDazkgfvBkVGgnnLUWXoxnomp5up8llg4", "sedol": null, "ticker_symbol": "EWZ", "type": "etf", "unofficial_currency_code": null, "update_datetime": null }, { "close_price": 1, "close_price_as_of": null, "cusip": null, "industry": null, "institution_id": null, "institution_security_id": null, "is_cash_equivalent": true, "isin": null, "iso_currency_code": "USD", "market_identifier_code": null, "name": "U S Dollar", "option_contract": null, "proxy_security_id": null, "sector": null, "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are", "sedol": null, "ticker_symbol": null, "type": "cash", "unofficial_currency_code": null, "update_datetime": null } ] } ``` --- # Investments Move - Introduction to Investments Move | Plaid Docs Introduction to Investments Move   ================================== #### Automate ACATS and reduce rejections with broker-sourced data  Get started with Investments Move [API Reference](https://plaid.com/docs/api/products/investments-move/index.html.md) #### Overview  Investments Move (US and CA only) allows you to obtain broker-sourced data to automate brokerage account transfers, reduce operational complexity, and avoid rejections. You can use Investments Move to replace your existing manual ACATS data entry flow or build a new, high-performing flow. Investments Move is designed to increase both the number of users who submit an ACATS transfer and the rate at which these requests successfully settle. Using Investments Move, a user accesses their brokerage account via a Plaid Link-initiated flow, and Plaid returns the source of truth data needed to submit an ACATS transfer, such as account number, account type, account holder name, holdings data, and DTC codes. For brokerages in Canada, Investments Move can retrieve the data necessary for an ATON transfer. Investments Move is currently in early availability and available on a limited basis. To request access, if you are new to Plaid, [contact sales](https://plaid.com/contact/) ; if you are already a Plaid customer, contact your account manager. Looking for investment holdings or trading activity, without initiating ACATS transfers? See [Investments](https://plaid.com/docs/investments/index.html.md) instead. #### Integration overview  The steps below show an overview of how to integrate Investments Move. 1. Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Along with any other parameters you specify, make sure to include the following: * The `products` array should be set to `["investments_auth"]`. * (Optional) To enable [fallback flows](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) , set the corresponding flag within the `investments_auth` object. For details, see [Fallback flows](https://plaid.com/docs/investments-move/index.html.md#fallback-flows) . 2. On the client side, create an instance of Link using the `link_token` returned by [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; for more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . 3. Once the end user has completed the Link flow, exchange the `public_token` for an `access_token` by calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . 4. Call the [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) endpoint with the `access_token` you received from the token exchange. This endpoint will return all the information needed to initiate an ACATS transfer, including account holder name, account number, and DTC number. #### Fallback flows  By default, an end user will only be able to select institutions where Plaid can obtain the full account number, account holder name, and holdings data. You can optionally choose to expand the number of institutions available by enabling one or more of the flows below, which allow the end user to directly enter data that Plaid was not able to obtain directly from the broker. To know what data came directly from the brokerage, what was entered by the user and verified against partial data from the brokerage, and what was entered by the user but not verified by the brokerage because no data was available, you can use the `data_sources` object in the [/investments/auth/get](https://plaid.com/docs/api/products/investments-move/index.html.md#investmentsauthget) response. ##### Masked Number Match  Masked Number Match supports institutions where Plaid is able to obtain broker-sourced holdings data and account holder information but can only obtain a partial (masked) account number, typically the last four digits of the account number. During the Link flow, the user will be prompted to enter their full account number, which will be verified against the partial account number; if the numbers do not match, the Link attempt will fail and the user will be required to re-enter the account number. To enable Masked Number Match, in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request, set `investments_auth.masked_number_match_enabled` to `true`. ##### Stated Account Number  Stated Account Number supports institutions where Plaid is able to obtain broker-sourced holdings data, and may or may not be able to obtain account holder information, but cannot obtain any part of an account number. During the Link flow, the user will be prompted to enter their full account number. If Plaid was unable to obtain account holder information, the user will also be prompted to enter their full name. To enable Stated Account Number, in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request, set `investments_auth.stated_account_number_enabled` to `true`. ##### Manual Entry  Manual Entry supports institutions where Plaid cannot return any information. During the Link flow, users will be able to manually enter the information needed to submit the ACATS transfer. Plaid will still attempt to standardize and enrich the data they provide. To enable Manual Entry, in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request, set `investments_auth.manual_entry_enabled` to `true`. #### Testing Investments Move  Investments Move can be tested in [Sandbox](https://plaid.com/docs/sandbox/index.html.md) without any additional permissions. To test fallback flows in Sandbox, use the institution Houndstooth Bank (`ins_109512`). The first fallback flow that is explicitly enabled in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call will be used. The flows will be attempted in the following order: Masked Number Match, Stated Account Number, and Manual Entry. (So for example, if both Masked Number Match and Manual Entry are enabled, Masked Number Match will be used.) #### Investments Move pricing  Investments Move is billed on a [per-request flat fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [contact sales](https://plaid.com/contact/) . --- # Investments - Add Investments to your app | Plaid Docs Add Investments to your app  ============================ #### Learn how to add Investments endpoints to your application  In this guide, we'll start from scratch and walk through how to use [Investments](https://plaid.com/docs/api/products/investments/index.html.md) to retrieve information on securities and holdings. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to [Fetching investment data](https://plaid.com/docs/investments/add-to-app/index.html.md#fetching-investment-data) . #### Get Plaid API keys and complete application and company profile  If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard. You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile and company profile must be completed before connecting to certain institutions in Production. #### Install and initialize Plaid libraries  You can use our official server-side client libraries to connect to the Plaid API from your application: ```node // Install via npm npm install --save plaid ``` ```bash ## Not applicable with curl calls ``` ```ruby # Available as a gem gem install plaid ``` ```java /* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ implementation "com.plaid:plaid-java:{VERSION}" /* For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ com.plaid plaid-java {VERSION} ``` ```python # Install through pip, only supports Python 3 pip install --upgrade plaid-python ``` ```go go get github.com/plaid/plaid-go ``` After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls. ```node // Using Express const express = require('express'); const app = express(); app.use(express.json()); const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const client = new PlaidApi(configuration); ``` ```bash ## Not applicable with curl calls ``` ```ruby require 'sinatra' require 'plaid' set :port, ENV['APP_PORT'] || 8000 configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) ``` ```java import java.net.*; import java.io.*; import retrofit2.Response; import java.util.Arrays; import com.sun.net.httpserver.*; import com.plaid.client.ApiClient; import com.plaid.client.request.PlaidApi; public class PlaidExample { private static final String CLIENT_ID = System.getenv("PLAID_CLIENT_ID"); private static final String SECRET = System.getenv("PLAID_SECRET"); public static void main(String[] args) { HttpServer server = HttpServer.create( new InetSocketAddress("localhost", 8000), 0); server.createContext("/create_link_token", new GetLinkToken()); server.setExecutor(null); server.start(); } // Additional server code goes here } ``` ```python import plaid from plaid.api import plaid_api from flask import Flask from flask import render_template from flask import request from flask import jsonify app = Flask(name) configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Additional server code goes here if __name__ == "__main__": app.run(port=8000) ``` ```go import ( "context" "net/http" "os" "github.com/gin-gonic/gin" "github.com/plaid/plaid-go/v3/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) func main() { r := gin.Default() // Server endpoints would be declared here // e.g. r.POST("/create_link_token", createLinkToken) r.POST("/create_link_token", createLinkToken) err := r.Run(":8000") if err != nil { panic("unable to start server") } } ``` #### Create an Item in Link  Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) . Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created. ##### Create a link\_token  ```node const request: LinkTokenCreateRequest = { loading_sample: true }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```python request = LinkTokenCreateRequest( loading_sample=True ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "loading_sample": true }' ``` ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { loading_sample: true } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```java LinkTokenCreateRequest request = new LinkTokenCreateRequest() .loadingSample(true); Response response = client .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```go request := plaid.NewLinkTokenCreateRequest( "Sample App App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetLoadingSample(true) linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() if err != nil { panic(err) } linkToken := linkTokenCreateResp.GetLinkToken(); ``` ##### Install Link dependency  index.html ```html Connect a bank ``` ##### Configure the client-side Link handler  app.js ```javascript const linkHandler = Plaid.create({ token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token to your app server. $.post('/exchange_public_token', { public_token: public_token, }); }, onExit: (err, metadata) => { // Optionally capture when your user exited the Link flow. // Storing this information can be helpful for support. }, onEvent: (eventName, metadata) => { // Optionally capture Link flow events, streamed through // this callback as your users connect an Item to Plaid. }, }); linkHandler.open(); ``` #### Get a persistent access\_token  Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call. Save the `access_token` and `item_id` in a secure datastore, as they're used to access Item data and identify webhooks, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it. ```node app.post('/api/exchange_public_token', async function ( request, response, next, ) { const publicToken = request.body.public_token; try { const tokenResponse = await client.itemPublicTokenExchange({ public_token: publicToken, }); // These values should be saved to a persistent database and // associated with the currently signed-in user const accessToken = tokenResponse.data.access_token; const itemID = tokenResponse.data.item_id; response.json({ public_token_exchange: 'complete' }); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-12345678-abcd-1234-abcd-1234567890ab" }' ``` ```ruby access_token = nil post '/api/exchange_public_token' do request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: params["public_token"] } ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response.access_token item_id = response.item_id content_type :json {public_token_exchange: "complete"}.to_json end ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; public class PlaidExample { ... static class GetAccessToken implements HttpHandler { private static PlaidClient plaidClient; private String publicToken; private String accessToken; private String itemId; public void handle(HttpExchange t) throws IOException { // Simplified pseudo-code for obtaining public_token InputStream is = t.getRequestBody(); publicToken = is.publicToken(); // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange public_token for an access_token ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response response = plaidClient .itemPublicTokenExchange(request) .execute(); // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken = response.body().getAccessToken(); itemId = response.body().getItemId(); String message = "{\"public_token_exchange\": \"complete\"}"; return Response .status(Response.Status.OK) .entity(message) .type(MediaType.APPLICATION_JSON) } } } ``` ```python access_token = None item_id = None @app.route('/exchange_public_token', methods=['POST']) def exchange_public_token(): global access_token public_token = request.form['public_token'] request = ItemPublicTokenExchangeRequest( public_token=public_token ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response['access_token'] item_id = response['item_id'] return jsonify({'public_token_exchange': 'complete'}) ``` ```go func getAccessToken(c *gin.Context) { ctx := context.Background() publicToken := c.PostForm("public_token") // exchange the public_token for an access_token exchangePublicTokenReq := plaid.NewItemPublicTokenExchangeRequest(publicToken) exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *exchangePublicTokenReq, ).Execute() // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken := exchangePublicTokenResp.GetAccessToken() itemID := exchangePublicTokenResp.GetItemId() c.JSON(http.StatusOK, gin.H{"public_token_exchange": "complete"}) } ``` #### Fetching investment data  Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. Once you've retrieved investment data for an account, you can then use it to analyze data such as trading activity, net worth, and asset allocations. Investments endpoints return two primary pieces of information about the investment account. The first is details on the holding itself (if using [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) ) or the transaction (if using [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) ). The second is details about the security itself. Each security, transaction, and holding contains a `security_id` field, which functions as a key for cross-referencing the holding or transaction with the security it pertains to. For more detailed information on the schema for information returned, see [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) or [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) . Investments data is typically updated daily, after market close. To be alerted when new data is available to be retrieved, listen to [Investments webhooks](https://plaid.com/docs/api/products/investments/index.html.md#webhooks) . ##### Fetching investment holdings  ```go import ( "context" "github.com/plaid/plaid-go/v40/plaid" ) holdingsGetReq := plaid.NewInvestmentsHoldingsGetRequest("ACCESS_TOKEN") holdingsGetReqOptions := plaid.NewInvestmentHoldingsGetRequestOptions() holdingsGetReqOptions.SetAccountIds([]string{"ACCOUNT_ID"}) holdingsGetReq.SetOptions(*holdingsGetReqOptions) holdingsGetResp, _, err = client.PlaidApi.InvestmentsHoldingsGet(ctx).InvestmentsHoldingsGetRequest( *holdingsGetReq, ).Execute() securities := holdingsGetResp.GetSecurities() holdings := holdingsGetResp.GetHoldings() ``` ```node const { InvestmentsHoldingsGetRequest } = require('plaid'); // Pull Holdings for an Item const request: InvestmentsHoldingsGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.investmentsHoldingsGet(request); const holdings = response.data.holdings; const securities = response.data.securities; } catch (error) { // handle error } ``` ```python import plaid from plaid.model.investments_holdings_get_request import InvestmentsHoldingsGetRequest # Pull Holdings for an Item request = InvestmentsHoldingsGetRequest(access_token=access_token) response = client.investments_holdings_get(request) # Handle Holdings response holdings = response['holdings'] # Handle Securities response securities = response['securities'] ``` ```ruby require 'plaid' # Pull Holdings for an Item request = Plaid::InvestmentsHoldingsGetRequest.new({ access_token: access_token }) response = client.investments_holdings_get(request) # Handle Holdings response holdings = response.holdings # Handle Securities response securities = response.securities ``` ```java import com.plaid.client.model.InvestmentsHoldingsGetRequest; import com.plaid.client.model.InvestmentsHoldingsGetResponse; // Pull Holdings for an Item InvestmentsHoldingsGetRequest request = new InvestmentsHoldingsGetRequest() .accessToken(accessToken); Response response = client() .investmentsHoldingsGet(request) .execute(); // Handle Holdings response List holdings = response.body().getHoldings(); // Handle Securities response List securities = response.body().getSecurities(); ``` ```bash curl -X POST https://sandbox.plaid.com/investments/holdings/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": string }' ``` Example response data is below. Sample investments holdings response ```json { "accounts": [ { "account_id": "5Bvpj4QknlhVWk7GygpwfVKdd133GoCxB814g", "balances": { "available": 43200, "current": 43200, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "4444", "name": "Plaid Money Market", "official_name": "Plaid Platinum Standard 1.85% Interest Money Market", "subtype": "money market", "type": "depository" }, { "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1", "balances": { "available": null, "current": 320.76, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "5555", "name": "Plaid IRA", "official_name": null, "subtype": "ira", "type": "investment" }, { "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm", "balances": { "available": null, "current": 23631.9805, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "6666", "name": "Plaid 401k", "official_name": null, "subtype": "401k", "type": "investment" } ], "holdings": [ { "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1", "cost_basis": 0.01, "institution_price": 0.011, "institution_price_as_of": null, "institution_price_datetime": null, "institution_value": 110, "iso_currency_code": "USD", "quantity": 10000, "vested_quantity": null, "vested_value": null, "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb", "unofficial_currency_code": null }, { "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm", "cost_basis": 23, "institution_price": 27, "institution_price_as_of": null, "institution_price_datetime": null, "institution_value": 636.309, "iso_currency_code": "USD", "quantity": 23.567, "vested_quantity": null, "vested_value": null, "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP", "unofficial_currency_code": null } ], "item": { "available_products": [ "balance", "credit_details", "identity", "investments", "liabilities", "transactions" ], "billed_products": ["assets", "auth", "investments"], "consent_expiration_time": null, "error": null, "institution_id": "ins_3", "item_id": "4z9LPae1nRHWy8pvg9jrsgbRP4ZNQvIdbLq7g", "webhook": "https://www.genericwebhookurl.com/webhook" }, "request_id": "l68wb8zpS0hqmsJ", "securities": [ { "close_price": 0.011, "close_price_as_of": null, "cusip": null, "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": null, "iso_currency_code": "USD", "name": "Nflx Feb 01'18 $355 Call", "proxy_security_id": null, "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb", "sedol": null, "ticker_symbol": "NFLX180201C00355000", "type": "derivative", "subtype": "option", "unofficial_currency_code": null, "update_datetime": null, "sector": "Technology Services", "industry": "Internet Software or Services", "market_identifier_code": "XNAS", "cfi_code": "OCASPS", "option_contract": { "contract_type": "call", "expiration_date": "2018-02-01", "strike_price": 355.00, "underlying_security_ticker": "NFLX" }, "fixed_income": null }, { "close_price": 27, "close_price_as_of": null, "cusip": "577130834", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US5771308344", "iso_currency_code": "USD", "name": "Matthews Pacific Tiger Fund Insti Class", "proxy_security_id": null, "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP", "sedol": null, "ticker_symbol": "MIPTX", "type": "mutual fund", "subtype": "mutual fund", "unofficial_currency_code": null, "update_datetime": null, "sector": "Miscellaneous", "industry": "Investment Trusts or Mutual Funds", "market_identifier_code": "XNAS", "cfi_code": "CIOIBS", "option_contract": null, "fixed_income": null } ] } ``` ##### Fetching investment transactions  ```bash curl -X POST https://sandbox.plaid.com/investments/transactions/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": string, "start_date": "2025-03-01", "end_date": "2025-04-30", "options": { "count": 250, "offset": 100 } }' ``` ```ruby # Pull investment transactions for a date range investments_transactions_get_request = Plaid::InvestmentsTransactionsGetRequest.new investments_transactions_get_request.access_token = access_token investments_transactions_get_request.start_date = '2025-03-01' investments_transactions_get_request.end_date = '2025-04-30' response = client.investments_transactions_get(investments_transactions_get_request) investment_transactions = response.investment_transactions ``` ```java SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd"); startDate = simpleDateFormat.parse("2025-03-01"); endDate = simpleDateFormat.parse("2025-04-30"); // Pull transactions for a date range InvestmentsTransactionsGetRequestOptions options = new InvestmentsTransactionsGetRequestOptions() .count(100) .offset(1); InvestmentsTransactionsGetRequest request = new InvestmentsTransactionsGetRequest() .accessToken(accessToken) .startDate(startDate) .endDate(endDate) .options(options); Response response = plaidClient .investmentsTransactionsGet(request) .execute(); for (InvestmentsTransactionsGetResponse.InvestmentTransaction txn : response.body().getInvestmentTransactions()) { ... } ``` ```node const request: InvestmentsTransactionsGetRequest = { access_token: accessToken, start_date: '2025-01-01', end_date: '2025-06-10', options: { count: 250, offset: 0, }, }; try { const response = await plaidClient.investmentsTransactionsGet(request); const investmentTransactions = response.data.investment_transactions; } catch (error) { // handle error } ``` ```python request = InvestmentsTransactionsGetRequest( access_token=access_token, start_date=datetime.date(2025, 3, 1), end_date=datetime.date(2025, 4, 30), ) response = client.investments_transactions_get(request) investment_transactions = response['investment_transactions'] # Manipulate the count and offset parameters to paginate # transactions and retrieve all available data while len(investment_transactions) < response['total_investment_transactions']: options = InvestmentsTransactionsGetRequestOptions(offset=len(investment_transactions)) request = InvestmentsTransactionsGetRequest( access_token=access_token, start_date=datetime.date(2025, 3, 1), end_date=datetime.date(2025, 4, 30), options=options ) response = client.investments_transactions_get(request) investment_transactions.extend(response['investment_transactions']) ``` ```go request := plaid.NewInvestmentsTransactionsGetRequest(accessToken, startDateString, endDateString) response, _, err := client.PlaidApi.InvestmentsTransactionsGet(ctx).InvestmentsTransactionsGetRequest(*request).Execute() investmentTransactions := response.GetInvestmentTransactions() ``` Sample response data is below. Investments transactions sample response ```json { "accounts": [ { "account_id": "5e66Dl6jNatx3nXPGwZ7UkJed4z6KBcZA4Rbe", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" }, { "account_id": "KqZZMoZmBWHJlz7yKaZjHZb78VNpaxfVa7e5z", "balances": { "available": null, "current": 320.76, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "5555", "name": "Plaid IRA", "official_name": null, "subtype": "ira", "type": "investment" }, { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "balances": { "available": null, "current": 23631.9805, "iso_currency_code": "USD", "limit": null, "margin_loan_amount": null, "unofficial_currency_code": null }, "mask": "6666", "name": "Plaid 401k", "official_name": null, "subtype": "401k", "type": "investment" } ], "investment_transactions": [ { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "amount": -8.72, "cancel_transaction_id": null, "date": "2020-05-29", "fees": 0, "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW", "iso_currency_code": "USD", "name": "INCOME DIV DIVIDEND RECEIVED", "price": 0, "quantity": 0, "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ", "subtype": "dividend", "type": "cash", "unofficial_currency_code": null }, { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "amount": -1289.01, "cancel_transaction_id": null, "date": "2020-05-28", "fees": 7.99, "investment_transaction_id": "pK99jB9e7mtwjA435GpVuMvmWQKVbVFLWme57", "iso_currency_code": "USD", "name": "SELL Matthews Pacific Tiger Fund Insti Class", "price": 27.53, "quantity": -47.74104242992852, "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP", "subtype": "sell", "type": "sell", "unofficial_currency_code": null }, { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "amount": 7.7, "cancel_transaction_id": null, "date": "2020-05-27", "fees": 7.99, "investment_transaction_id": "LKoo1ko93wtreBwM7yQnuQ3P5DNKbKSPRzBNv", "iso_currency_code": "USD", "name": "BUY DoubleLine Total Return Bond Fund", "price": 10.42, "quantity": 0.7388014749727547, "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk", "subtype": "buy", "type": "buy", "unofficial_currency_code": null } ], "item": { "available_products": ["assets", "balance", "identity", "transactions"], "billed_products": ["auth", "investments"], "consent_expiration_time": null, "error": null, "institution_id": "ins_12", "item_id": "8Mqq5rqQ7Pcxq9MGDv3JULZ6yzZDLMCwoxGDq", "webhook": "https://www.genericwebhookurl.com/webhook" }, "request_id": "iv4q3ZlytOOthkv", "securities": [ { "close_price": 27, "close_price_as_of": null, "cusip": "577130834", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US5771308344", "iso_currency_code": "USD", "name": "Matthews Pacific Tiger Fund Insti Class", "proxy_security_id": null, "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP", "sedol": null, "ticker_symbol": "MIPTX", "type": "mutual fund", "subtype": "mutual fund", "unofficial_currency_code": null, "update_datetime": null, "sector": "Miscellaneous", "industry": "Investment Trusts or Mutual Funds", "market_identifier_code": "XNAS", "cfi_code": "CIOIBS", "option_contract": null, "fixed_income": null }, { "close_price": 10.42, "close_price_as_of": null, "cusip": "258620103", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US2586201038", "iso_currency_code": "USD", "name": "DoubleLine Total Return Bond Fund", "proxy_security_id": null, "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk", "sedol": null, "ticker_symbol": "DBLTX", "type": "mutual fund", "subtype": "mutual fund", "unofficial_currency_code": null, "update_datetime": null, "sector": "Miscellaneous", "industry": "Investment Trusts or Mutual Funds", "market_identifier_code": "XNAS", "cfi_code": "CIOIBS", "option_contract": null, "fixed_income": null } ], "total_investment_transactions": 2 } ``` #### Next steps  If you're ready to launch to Production, see the Launch checklist. #### Launch checklist  Recommended steps to take before launching in Production [Launch](https://plaid.com/docs/launch-checklist/index.html.md) --- # Investments - Introduction to Investments | Plaid Docs Introduction to Investments   ============================= #### View holdings and transactions from investment accounts  Get started with Investments [API Reference](https://plaid.com/docs/api/products/investments/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md) #### Overview  The Investments product allows you to obtain holding, security, and transactions data for investment-type accounts in financial institutions within the United States and Canada. This data can be used for personal financial management tools and wealth management analysis. Looking for Plaid's solution to automate ACATS transfers and avoid friction, failures, and delays due to manual data entry? See [Investments Move](https://plaid.com/docs/investments-move/index.html.md) instead. [Prefer to learn by watching? Get an overview of how Investments works in just 3 minutes!](https://www.youtube.com/watch?v=DYiKaQgYJ74) #### Securities and holdings  The [/investments/holdings/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentsholdingsget) endpoint provides both security data and holding data. Security data represents information about a specific security, such as its name, ticker symbol, and price. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data. Sample security data ```json { "close_price": 10.42, "close_price_as_of": null, "cusip": "258620103", "institution_id": null, "institution_security_id": null, "is_cash_equivalent": false, "isin": "US2586201038", "iso_currency_code": "USD", "name": "DoubleLine Total Return Bond Fund", "proxy_security_id": null, "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk", "sedol": null, "ticker_symbol": "DBLTX", "type": "mutual fund", "subtype": "mutual fund", "unofficial_currency_code": null, "update_datetime": null, "sector": "Miscellaneous", "industry": "Investment Trusts or Mutual Funds", "market_identifier_code": "XNAS", "cfi_code": "CIOIBS", "option_contract": null, "fixed_income": null } ``` Holding data, by contrast, represents information about a user's specific ownership of that security, such as the number of shares owned and the cost basis. Each holding includes a `security_id` field that can be cross-referenced to a security for more detailed information about the security itself. Sample holding data ```json { "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm", "cost_basis": 10, "institution_price": 10.42, "institution_price_as_of": null, "institution_price_datetime": null, "institution_value": 20.84, "iso_currency_code": "USD", "quantity": 2, "vested_quantity": null, "vested_value": null, "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk", "unofficial_currency_code": null } ``` #### Transactions  The [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) endpoint provides up to 24 months of investment transactions data. The schema for investment transactions is not the same as for transactions data returned by the [Transactions](https://plaid.com/docs/transactions/index.html.md) product, instead providing securities-specific information. Inflow, such as stock sales, is shown as a negative amount, and outflow, such as stock purchases, is positive. The [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) endpoint can only be used for investment-type accounts; for obtaining transaction history for other account types, use [Transactions](https://plaid.com/docs/transactions/index.html.md) . Sample transaction data ```json { "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj", "amount": -8.72, "cancel_transaction_id": null, "date": "2020-05-29", "fees": 0, "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW", "iso_currency_code": "USD", "name": "INCOME DIV DIVIDEND RECEIVED", "price": 0, "quantity": 0, "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ", "subtype": "dividend", "type": "cash", "unofficial_currency_code": null } ``` #### Investments transactions initialization behavior  Unlike the Transactions product, by default, Investments Transactions operates synchronously and will not fire a webhook to indicate when initial data is ready for an Item. If investments transactions data is not ready when [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) is first called, Plaid will wait for the data. For this reason, calling [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) immediately after Link may take up to one to two minutes to return. If you are adding Investments to an Item by calling [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) [after the Item was originally linked](https://plaid.com/docs/link/initializing-products/index.html.md#adding-products-post-link) , instead of specifying the Investments product while calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , you can optionally request asynchronous behavior by specifying `async_update=true`. In this case, Investments will fire a [HISTORICAL\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#investments_transactions-historical_update) webhook when data is ready to be fetched. In all other scenarios, Investments endpoints will operate synchronously and will not fire a webhook to indicate when the Item's initial data is available to be fetched. #### Investments updates and webhooks  Investments data is not static, since users' holdings will change as they trade and as market prices fluctuate. Plaid typically checks for updates to investment data overnight, after market hours. You can also request an update on-demand via the [/investments/refresh](https://plaid.com/docs/api/products/investments/index.html.md#investmentsrefresh) endpoint, which is available as an add-on for Investments customers. To request access to this endpoint, submit a [product access request](https://dashboard.plaid.com/settings/team/products) or contact your Plaid account manager. There are two webhooks that are used for informing you of changes to investment data. The [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#holdings-default_update) webhook of type `HOLDINGS` fires when new holdings have been detected or the quantity or price of an existing holding has changed. The [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/investments/index.html.md#investments_transactions-default_update) webhook of type `INVESTMENTS_TRANSACTIONS` fires when a new or canceled investment transaction has been detected. When updating an Item with new Investments transactions data, it is recommended to call [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) with only the date range that needs to be updated, rather than the maximum available date range, in order to reduce the amount of data that you must receive and process. #### Investments institution coverage  By default, Investments provides access to data at over 2,400 institutions in the US and Canada. For details, see [Institution Coverage](https://plaid.com/docs/institutions/index.html.md) . Access to Fidelity Investments is granted automatically for all new customers on Growth or Custom plans and becomes effective approximately 8 weeks after Production access has been granted. If you need faster access for business reasons, contact your account manager. Customers on Pay-as-you-go plans must manually request access to Fidelity. Pay-as-you-go customers should contact support to request access. #### Testing Investments  Investments can be tested in [Sandbox](https://plaid.com/docs/sandbox/index.html.md) without any additional permissions. To test with realistic data, use the [custom user](https://github.com/plaid/sandbox-custom-users) . If provided real-world ticker symbols, Plaid will automatically populate securities with realistic data for both options and contracts. For examples, see the [sample Investments custom user](https://github.com/plaid/sandbox-custom-users/blob/main/investments/brokerage_custom_user.json) . When using the custom Sandbox user, Investments must be placed in the `products` array of [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and cannot be used in the `optional_products`, `additional_consented_products`, or `required_if_supported_products` array. Omitting `investments` from the `products` array may cause custom Sandbox investments data not to be loaded. #### Investments pricing  Investments is billed on a [subscription model](https://plaid.com/docs/account/billing/index.html.md#subscription-fee) ; Investments Refresh is billed on a [per-request flat fee model](https://plaid.com/docs/account/billing/index.html.md#per-request-flat-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) . #### Next steps  To get started building with Investments, see [Add Investments to your App](https://plaid.com/docs/investments/add-to-app/index.html.md) . If you're ready to launch to Production, see the Launch Center. #### Launch Center  See next steps to launch in Production [Launch](https://dashboard.plaid.com/developers/launch-center) --- # KYC/AML and anti-fraud | Plaid Docs KYC, AML, and anti-fraud products  ================================== #### Review and compare solutions  Overview and comparison of KYC, AML, and anti-fraud solutions Plaid offers Identity Verification for KYC (Know Your Customer) compliance, Monitor for AML (Anti Money Laundering) compliance, and Beacon (beta) for anti-fraud. The three products are tightly integrated and managed through a single dashboard but can also be used separately. Plaid Identity is also an anti-fraud solution targeted specifically at account takeover fraud. Because it's designed for payments use cases, you can learn more about it on the [Payments products](https://plaid.com/docs/payments/index.html.md) page. #### Identity Verification  [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) is Plaid's KYC solution. Via an interactive session with the user, Identity Verification allows you to check user-provided identity information such as name, ID number, phone number, and address against high-trust identity databases; check identity documents for expiration, signs of fraud, or mismatch with other user-provided data; run selfie verification to confirm liveness and photo ID matching; verify a user's phone number via SMS; and analyze a user's session, behavior, and identity details for signs of fraud. Identity Verification can also be run as a fully background session without interactivity (for checking pre-collected user data against databases only). Identity Verification can plug directly into Monitor for automatic AML watchlist scanning. Identity Verification is a separate product from Identity / Identity Match, but can integrate directly with [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) to reduce account takeover fraud risk when a user has linked a financial account to your application. Identity Match will verify that the ownership details (such as name, address, and phone number) on the linked account match the data verified via Identity Verification. #### Monitor  [Monitor](https://plaid.com/docs/monitor/index.html.md) provides AML capabilities, screening users against PEP (Politically Exposed Person) and sanction lists. Monitor is frequently used with Identity Verification -- integrating Monitor into an existing Identity Verification deployment can be as simple as checking a box on your Identity Verification template -- but can also be deployed separately. Any watchlist hits will be exposed via both a user-friendly dashboard UI and via API, for use with either manual or automated review workflows. #### Monitor and Identity Verification comparison  | | Identity Verification | Monitor | | --- | --- | --- | | Summary | Flexible and configurable KYC compliance to verify identity and detect fraud | Scan users against watchlists for AML compliance | | Supported countries | 190+ countries | 190+ countries | | UI languages | English, French, Spanish, Japanese, Portuguese | N/A | | Billing plans available | Pay-as-you-go or 12-month contract | Pay-as-you-go or 12-month contract | ##### Beacon  Beacon is Plaid's free network for fraud detection. You can scan all new users with Beacon to see whether they have any known fraud alerts from the Beacon Network. You can also be alerted when a new incident of fraud is reported on a user you have already added. These capabilities are available free of charge to all Plaid customers. --- # Launch checklist | Plaid Docs Launch in Production checklist  =============================== #### Check off these recommended steps before launching your app in Production  The Launch Checklist has been replaced by the [Launch Center](https://dashboard.plaid.com/developers/launch-center) . The Launch Center shows a personalized list of steps for your integration, with links to supporting materials like videos, sample code, and docs. The Launch Checklist is no longer being updated. Below is a list of recommended steps to take before launching your Plaid integration in production. While they might not all be required for the minimal operation of your application, the steps below will help to make your Plaid integration more robust, secure, efficient, and maintainable. For a similar list of steps in a PDF guide format, see the [Plaid implementation handbook](https://plaid.com/documents/plaid-implementation-handbook.pdf) . #### Production setup  #### Link setup  Follow the steps below to assist users in completing the Link flow, help ensure compliance with Plaid's policies, and avoid being billed for unneeded products. You may find it helpful to know that some of our customers link to Plaid's privacy policy within their own privacy policy, while others surface a separate just-in-time notice and consent page during their onboarding flow. Ultimately, it is up to you to determine how to obtain any legally required consents. ##### Callbacks  Handle callbacks beyond just `onSuccess` in order to gracefully handle errors and build analytics around Link. #### Webhook configuration  Plaid uses webhooks for many common flows. If your integration does any of the following, webhooks are required or strongly recommended: * (Any product) Your application is calling a Plaid endpoint for an Item repeatedly, over a period of time, not just immediately after Link. * (Transactions or Investments) You are accessing transactions made after the end user linked their Item. * (Auth) You are using automated micro-deposits for account verification, or making transfers over a year after the Item was initially linked. * (Assets) You are creating Asset Reports. * (Income) You are verifying a user's income. * (Payment Initiation (UK and Europe)) You are initiating payments. * (Virtual Accounts (UK and Europe) or Transfer) You are sending or receiving funds. #### Error handling  #### Link in update mode  Update mode is used to fix Items that have entered an error state (for example, because a user changed their password). If your application needs to access an Item repeatedly over a period of time, rather than just immediately after Link, implementing update mode logic is strongly recommended. #### Storage & logging  Log Plaid identifiers and IDs properly to enhance security, when contacting Support about a specific request or callback, and for finding specific entries in the [Activity Log](https://dashboard.plaid.com/activity/logs) . For more information, see [Dashboard logs and troubleshooting](https://plaid.com/docs/account/activity/index.html.md) . Ensure that the following identifiers are securely logged, as they will be needed when contacting Support about a specific request or callback. #### Item management  #### Multi-app use cases  ### Product-specific recommendations  #### Auth  If you are using Auth for an account funding use case, see the [Plaid account funding guide](https://plaid.com/documents/plaid-account-funding-guide.pdf) for use case specific recommendations. #### Balance  If you are using Balance for an account funding use case, see the [Plaid account funding guide](https://plaid.com/documents/plaid-account-funding-guide.pdf) for use case specific recommendations. #### Identity  If you are using Identity for an account funding use case, see the [Plaid account funding guide](https://plaid.com/documents/plaid-account-funding-guide.pdf) for use case specific recommendations. #### Transactions  #### Investments  #### Assets  #### Payment Initiation  #### Virtual Accounts  #### Income  See the [Plaid income verification solution guide](https://plaid.com/documents/plaid-income-verification-solution-guide.pdf) for use case specific recommendations. #### Identity Verification  See the [Plaid Identity Verification and Monitor solution guide](https://plaid.com/documents/plaid-idv-monitor-solution-guide.pdf) for use case specific recommendations. #### Monitor  See the [Plaid Identity Verification and Monitor solution guide](https://plaid.com/documents/plaid-idv-monitor-solution-guide.pdf) for use case specific recommendations. --- # Layer - Add Plaid Layer to your app | Plaid Docs Plaid Layer integration guide  ============================== #### Use Plaid Layer to instantly onboard new customers  In this guide, we'll start from scratch and walk through how to use [Plaid Layer](https://plaid.com/docs/api/products/layer/index.html.md) to create a fast, frictionless onboarding experience for your customers. If you're already familiar with Link, you can skip to [Create a Link token](https://plaid.com/docs/layer/add-to-app/index.html.md#create-a-link-token) . #### Get Plaid API keys and complete application and company profile  If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard. You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) in the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . #### Install and initialize Plaid libraries  You can use our official server-side client libraries to connect to the Plaid API from your application: ```node // Install via npm npm install --save plaid ``` ```bash ## Not applicable with curl calls ``` ```ruby # Available as a gem gem install plaid ``` ```java /* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ implementation "com.plaid:plaid-java:{VERSION}" /* For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ com.plaid plaid-java {VERSION} ``` ```python # Install through pip, only supports Python 3 pip install --upgrade plaid-python ``` ```go go get github.com/plaid/plaid-go ``` After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls. ```node // Using Express const express = require('express'); const app = express(); app.use(express.json()); const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const client = new PlaidApi(configuration); ``` ```bash ## Not applicable with curl calls ``` ```ruby require 'sinatra' require 'plaid' set :port, ENV['APP_PORT'] || 8000 configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) ``` ```java import java.net.*; import java.io.*; import retrofit2.Response; import java.util.Arrays; import com.sun.net.httpserver.*; import com.plaid.client.ApiClient; import com.plaid.client.request.PlaidApi; public class PlaidExample { private static final String CLIENT_ID = System.getenv("PLAID_CLIENT_ID"); private static final String SECRET = System.getenv("PLAID_SECRET"); public static void main(String[] args) { HttpServer server = HttpServer.create( new InetSocketAddress("localhost", 8000), 0); server.createContext("/create_link_token", new GetLinkToken()); server.setExecutor(null); server.start(); } // Additional server code goes here } ``` ```python import plaid from plaid.api import plaid_api from flask import Flask from flask import render_template from flask import request from flask import jsonify app = Flask(name) configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Additional server code goes here if __name__ == "__main__": app.run(port=8000) ``` ```go import ( "context" "net/http" "os" "github.com/gin-gonic/gin" "github.com/plaid/plaid-go/v3/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) func main() { r := gin.Default() // Server endpoints would be declared here // e.g. r.POST("/create_link_token", createLinkToken) r.POST("/create_link_token", createLinkToken) err := r.Run(":8000") if err != nil { panic("unable to start server") } } ``` #### Launch Link  Plaid Link is a drop-in module that provides a secure, elegant flow for Layer. Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created. ##### Create a Link token  Unlike a regular Link flow, the starting point for Layer is a call to [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) with a specified `TEMPLATE_ID`. The template should be created and configured in the dashboard ahead of time. If you want to use other products in addition to the `layer` product, make sure your template has them enabled. ```node app.post('/api/create_session_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const sessionTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, template_id: TEMPLATE_ID, }; try { const createTokenResponse = await client.sessionTokenCreate(sessionTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/session/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "template_id": "${TEMPLATE_ID}" }' ``` ```ruby post '/api/create_session_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a session_token for the given user request = Plaid::SessionTokenCreateRequest.new( { user: { client_user_id: client_user_id }, template_id: TEMPLATE_ID } ) response = client.session_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.SessionTokenCreateRequest; import com.plaid.client.model.SessionTokenCreateRequestUser; import com.plaid.client.model.SessionTokenCreateResponse; public class PlaidExample { ... static class GetSessionToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; SessionTokenCreateRequestUser user = new SessionTokenCreateRequestUser() .clientUserId(clientUserId); // Create a session_token for the given user SessionTokenCreateRequest request = new SessionTokenCreateRequest() .user(user) .templateId(TEMPLATE_ID); Response response = plaidClient .sessionTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.session_token_create_request import SessionTokenCreateRequest from plaid.model.session_token_create_request_user import SessionTokenCreateRequestUser @app.route("/create_session_token", methods=['POST']) def create_session_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a session_token for the given user request = SessionTokenCreateRequest( user=SessionTokenCreateRequestUser( client_user_id=client_user_id ), template_id=TEMPLATE_ID ) response = client.session_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createSessionToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a session_token for the given user request := plaid.NewSessionTokenCreateRequest(TEMPLATE_ID, *plaid.NewSessionTokenCreateRequestUser(clientUserId)) resp, _, err := testClient.PlaidApi.SessionTokenCreate(ctx).SessionTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "session_token": resp.GetLink().GetLinkToken(), }) } ``` ##### Install the Link SDKs  For instructions on installing Link SDKs, see the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform: [iOS](https://plaid.com/docs/link/ios/index.html.md) , [Android](https://plaid.com/docs/link/android/index.html.md) , [React Native](https://plaid.com/docs/link/react-native/index.html.md) , or [React](https://plaid.com/docs/link/web/index.html.md) . Layer is not supported on mobile webview integrations. As Plaid is actively adding new Layer functionality, it is strongly recommended that you use the latest SDK version if your app uses Layer. If you are developing a native mobile application, Layer requires SDK versions from June 2024 or later. Minimum versions are 6.0.4 (iOS), 4.5.0 (Android), and 11.11.0 (React Native). For Extended Autofill support, minimum versions are 6.3.1 (iOS), 5.3.0 (Android), 12.4.0 (React Native), and 4.1.1 (React). Layer is not compatible with the [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) integration mode. ##### Create the Link Handler  Basic sample code for creating the Link handler is shown below. For more details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform: [iOS](https://plaid.com/docs/link/ios/index.html.md) , [Android](https://plaid.com/docs/link/android/index.html.md) , [React Native](https://plaid.com/docs/link/react-native/index.html.md) , or [React](https://plaid.com/docs/link/web/index.html.md) . Ensure you are creating a Link token and passing it to the Link SDK as early as possible. The more time between when you create your handler and when you open Link, the better the UX will be for your users. If you already have an existing Android or React Native integration created prior to June 2024, you will likely need to update your client-side Link opening code to support Layer. If your Android integration does not use a `PlaidHandler` or uses `OpenPlaidLink` instead of `FastOpenPlaidLink`, or if your React Native integration uses `PlaidLink` instead of `create` and `open`, you will need to add a separate handler creation step, as shown in the sample code below. For more details, see [React Native: opening Link](https://plaid.com/docs/link/react-native/index.html.md#opening-link) and [Android: opening Link](https://plaid.com/docs/link/android/index.html.md#create-a-linktokenconfiguration) . Select group for content switcher AndroidiOSReact NativeWeb ##### Create a LinkTokenConfiguration  Each time you open Link, you will need to get a new `link_token` from your server and create a new `LinkTokenConfiguration` object with it. ```kotlin val linkTokenConfiguration = linkTokenConfiguration { token = "LINK_TOKEN_FROM_SERVER" } ``` ```java LinkTokenConfiguration linkTokenConfiguration = new LinkTokenConfiguration.Builder() .token("LINK_TOKEN_FROM_SERVER") .build(); ``` The Link SDK runs as a separate `Activity` within your app. In order to return the result to your app, it supports both the standard `startActivityForResult` and `onActivityResult` and the `ActivityResultContract` [result APIs](https://developer.android.com/training/basics/intents/result) . Select group for content switcher Activity Result APIsStandard Activity APIs ##### Register a callback for an Activity Result  ```kotlin private val linkAccountToPlaid = registerForActivityResult(FastOpenPlaidLink()) { when (it) { is LinkSuccess -> /* handle LinkSuccess */ is LinkExit -> /* handle LinkExit */ } } ``` ```java private ActivityResultLauncher linkAccountToPlaid = registerForActivityResult(new FastOpenPlaidLink(), result -> { if (result instanceof LinkSuccess) { /* handle LinkSuccess */ } else { /* handle LinkExit */ } } ); ``` ##### Create a PlaidHandler  ```kotlin val plaidHandler: PlaidHandler = Plaid.create(application, linkTokenConfiguration) ``` ```java plaidHandler = Plaid.create(this.getApplication(), linkTokenConfiguration); ``` ##### Open Link  ```kotlin linkAccountToPlaid.launch(plaidHandler) ``` ```java linkAccountToPlaid.launch(plaidHandler); ``` ##### Create a Configuration  Once the Link token is passed to your app, you will create an instance of `LinkTokenConfiguration`, then create a Handler using `Plaid.create()` passing the previously created `LinkTokenConfiguration`. ```swift var linkConfiguration = LinkTokenConfiguration( token: "<#LINK_TOKEN_FROM_SERVER#>", onSuccess: { linkSuccess in // Send the linkSuccess.publicToken to your app server. } ) ``` ```objectivec PLKLinkTokenConfiguration* linkConfiguration = [PLKLinkTokenConfiguration createWithToken:"<#LINK_TOKEN_FROM_SERVER#>" onSuccess:^(PLKLinkSuccess *linkSuccess) { // Send the linkSuccess.publicToken to your app server. }]; ``` ##### Create a Handler  A `Handler` is a one-time use object used to open a Link session. The `Handler` must be retained for the duration of the Plaid SDK flow. It will also be needed to respond to OAuth Universal Link redirects. For more details, see the [OAuth guide](https://plaid.com/docs/link/oauth/index.html.md#ios) . ```swift let result = Plaid.create(configuration) switch result { case .failure(let error): logger.error("Unable to create Plaid handler due to: \(error)") case .success(let handler): self.handler = handler } ``` ```objectivec NSError *createError = nil; id handler = [PLKPlaid createWithLinkTokenConfiguration:linkConfiguration error:&createError]; if (handler) { self.linkHandler = handler; } else if (createError) { NSLog(@"Unable to create PLKHandler due to: %@", createError); } ``` Initiate the Link preloading process by invoking the `create` function. Invoke Link create method ```javascript { create({token: linkToken}); setDisabled(false); } }> Create Link ``` Call `Plaid.create` (or, if using React, `usePlaidLink`) when initializing the view that is responsible for loading Plaid. ```javascript const handler = Plaid.create({ token: 'GENERATED_LINK_TOKEN', onSuccess: (public_token, metadata) => {}, onLoad: () => {}, onExit: (err, metadata) => {}, onEvent: (eventName, metadata) => {}, }); ``` ```tsx // The usePlaidLink hook manages Plaid Link creation // It does not return a destroy function; // instead, on unmount it automatically destroys the Link instance const config: PlaidLinkOptions = { onSuccess: (public_token, metadata) => {}, onExit: (err, metadata) => {}, onEvent: (eventName, metadata) => {}, token: 'GENERATED_LINK_TOKEN', }; const { open, exit, ready, submit } = usePlaidLink(config); ``` #### Submit the user's phone number  Call the `submit` method on the Plaid handler you created earlier with the user's phone number. The semantics depend on the language/platform, but all methods are called `submit`. Select group for content switcher AndroidiOSReact NativeWeb ```kotlin val submissionData = SubmissionData(phoneNumber) plaidHandler.submit(submissionData) ``` ```java SubmissionData submissionData = new SubmissionData(phoneNumber); plaidHandler.submit(submissionData); ``` Swift sample code ```swift // Create a model that conforms to the SubmissionData interface struct PlaidSubmitData: SubmissionData { var phoneNumber: String? } let data = PlaidSubmitData(phoneNumber: "14155550015") self.handler.submit(data) ``` ```javascript submit({ "phone_number": "+14155550123" }) ``` ```javascript handler.submit({ "phone_number": "+14155550123" }) ``` #### Submit the user's date of birth  Upon receiving `LAYER_NOT_AVAILABLE` after phone number submission, collect the user's date of birth and call the `submit` method on the existing Plaid handler. For more details, see [Extended Autofill](https://plaid.com/docs/layer/index.html.md#extended-autofill) . This functionality requires minimum SDK versions 6.3.1 (iOS), 5.3.0 (Android), 12.4.0 (React Native), and 4.1.1 (React). If you are using an older SDK version or do not wish to use Extended Autofill, you can skip this step. Select group for content switcher AndroidiOSReact NativeWeb ```kotlin val submissionData = SubmissionData(dateOfBirth = "1975-01-18") plaidHandler.submit(submissionData) ``` ```java SubmissionData submissionData = new SubmissionData("1975-01-18"); plaidHandler.submit(submissionData); ``` Swift sample code ```swift // Create a model that conforms to the SubmissionData interface struct PlaidSubmitData: SubmissionData { var dateOfBirth: String? var phoneNumber: String? } let data = PlaidSubmitData(dateOfBirth: "1975-01-18") self.handler.submit(data) ``` ```javascript submit({ "dateOfBirth": "1975-01-18" }) ``` ```javascript handler.submit({ "date_of_birth": "1975-01-18" }) ``` #### Open Layer UI on the LAYER\_READY event  Listen to the events on the Plaid handler via `onEvent`. For platform-specific details, see the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform. If you receive `LAYER_READY`, the user is eligible for the Layer flow and you should proceed to open Link according to the [Link documentation](https://plaid.com/docs/link/index.html.md) for your platform. If you receive `LAYER_AUTOFILL_NOT_AVAILABLE` (or if you receive `LAYER_NOT_AVAILABLE` and have not built Extended Autofill support for your integration), the user is not eligible for the Layer flow. You can clean up the handler you created earlier and fall back to whatever non-Layer onboarding flow fits your application (e.g. a traditional Link session, or other custom flow for your app). Select group for content switcher AndroidiOSReact NativeWeb ```kotlin Plaid.setLinkEventListener { event -> when(event.eventName) { is LAYER_READY -> { // open link linkAccountToPlaid.launch(plaidHandler) } is LAYER_NOT_AVAILABLE -> { // run fall back flow } else -> { Log.i("Event", event.toString()) } } } ``` ```java Plaid.setLinkEventListener(new LinkEventListener() { @Override public void onEvent(LinkEvent event) { switch (event.getEventName()) { case LAYER_READY: // Open link linkAccountToPlaid.launch(plaidHandler); break; case LAYER_NOT_AVAILABLE: // Run fallback flow break; default: Log.i("Event", event.toString()); } } }); ``` Swift sample code ```swift var linkSessionID: String? linkTokenConfiguration.onEvent = { [weak self] linkEvent in guard let self = self else { return } switch linkEvent.eventName { case .layerReady: self.handler.open(presentUsing: .viewController(self)) break case .layerNotAvailable: // Fall back on non-Layer flows, clean up break default: // Other cases ignored in this use case. break } } ``` JavaScript sample code ```javascript usePlaidEmitter((event: LinkEvent) => { switch (event.eventName) { case LinkEventName.LAYER_READY: // Open Link open({...}) break; case LinkEventName.LAYER_NOT_AVAILABLE: // Run another fallback flow break; default: // Other cases ignored in this use case break; } }); ``` JavaScript sample code ```javascript //Same onEvent handler from Link create sample onEvent: (eventName, metadata) => { switch(eventName) { case "LAYER_READY": // Open Link open({...}) break; case "LAYER_NOT_AVAILABLE": // Run another fallback flow break; default: //Other cases ignored in this use case break; } } ``` #### Get the public token from the onSuccess callback  On successful completion, an `onSuccess` callback will be invoked, similar to the standard Link flow. Capture the `public_token` from `onSuccess`. Select group for content switcher AndroidiOSReact NativeWeb ```kotlin val profileToken = success.publicToken // Send the public token to your backend ``` ```java String profileToken = success.getPublicToken(); // Send the public token to your backend ``` Swift sample code ```swift onSuccess: { linkSuccess in } // Send the public token to your backend ``` JavaScript sample code ```javascript const onSuccess = (linkSuccess: LinkSuccess) => { let publicToken = linkSuccess.publicToken; // Send the public token to your backend }; ``` JavaScript sample code ```javascript onSuccess: (public_token) => { const publicToken = public_token; // Send the public token to your backend }; ``` #### Get user account data  Call [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) to retrieve user-permissioned identity information as well as Item access tokens. Unlike typical Plaid Link sessions, where you must first exchange your public token for an access token in order to talk to the Plaid API, the [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) endpoint allows you to retrieve user-permissioned identity information as well as Item access tokens in a single call. You can optionally use Plaid products such as [Identity Match](https://plaid.com/docs/identity/index.html.md#identity-match) or [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) if you wish to verify this data. Because Layer already verifies your user's phone number via OTP or SNA, for a low-friction experience, you should _not_ perform additional OTP phone number verification as long as Layer has verified the number. The best indication that the number was verified is the [LAYER\_AUTHENTICATION\_PASSED](https://plaid.com/docs/api/products/layer/index.html.md#layer_authentication_passed) webhook. Before skipping OTP verification based on this webhook, be sure to implement [webhook verification](https://plaid.com/docs/api/webhooks/webhook-verification/index.html.md) to protect against webhook spoofing attacks. Alternatively, you can use Link completion to indicate that the number was verified, but this method will exclude sessions where the user verified their number without fully completing Link. To use this method, call `/user_account/session_get`; the `phone_number` returned is the verified number. Do not rely on the `onSuccess` callback, as this can be vulnerable to client-side spoofing attacks. ```node const request: UserAccountSessionGetRequest = { public_token: 'profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d', }; try { const response = await client.userAccountSessionGet(request); } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/user_account/session/get \ -H 'Content-Type: application/json' \ -d '{ "public_token": "profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d", "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}" }' ``` ```ruby request = Plaid::UserAccountSessionGetRequest.new( { public_token: 'profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d' } ) response = client.user_account_session_get(request) ``` ```java UserAccountSessionGetRequest request = new UserAccountSessionGetRequest() .publicToken("profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d"); Response response = client() .userAccountSessionGet(request) .execute(); ``` ```python request = UserAccountSessionGetRequest( public_token=PublicToken('profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d') ) response = client.user_account_session_get(request) ``` ```go request := plaid.NewUserAccountSessionGetRequest( "profile-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce992d", ) response, _, err := client.PlaidApi. UserAccountSessionGet(ctx). UserAccountSessionGetRequest(*request). Execute() ``` Layer sample response ```json { "identity": { "phone_number": "+14155550015", "name": { "first_name": "Leslie", "last_name": "Knope" }, "address": { "street": "123 Main St.", "street2": "Apt 123", "city": "Pawnee", "region": "Indiana", "postal_code": "46001", "country": "US" }, "email": "leslie@knope.com", "date_of_birth": "1979-01-01", "ssn": "987654321", "ssn_last4": "4321" }, "identity_edit_history": { "name": { "edits_current": 0, "edits_1d": 0, "edits_30d": 1, "edits_365d": 1, "edits_all_time": 1 }, "address": { "edits_current": 1, "edits_1d": 1, "edits_30d": 2, "edits_365d": 2, "edits_all_time": 2 }, "email": { "edits_current": 0, "edits_1d": 0, "edits_30d": 0, "edits_365d": 0, "edits_all_time": 0 }, "date_of_birth": { "edits_current": 0, "edits_1d": 0, "edits_30d": 0, "edits_365d": 0, "edits_all_time": 0 }, "official_document": { "ssn": { "edits_current": 0, "edits_1d": 0, "edits_30d": 0, "edits_365d": 0, "edits_all_time": 0 } } }, "items": [ { "item_id": , "access_token": "access-token-" } ], "request_id": "j0LkqT9OPdVwjwh" } ``` --- # Layer - Introduction to Plaid Layer | Plaid Docs Introduction to Plaid Layer   ============================= #### Onboard users instantly with just a phone number  Get started with Plaid Layer [API Reference](https://plaid.com/docs/api/products/layer/index.html.md) [Quickstart](https://github.com/plaid/layer-quickstart) [Demo](https://plaid.coastdemo.com/share/6717daecf618361b93d583f5?zoom=100) [Request Access](https://plaid.com/layer/#contact-form) #### Overview  Instantly onboard millions of people from the Plaid Network with Layer (US only). When a user provides their phone number, Plaid Layer checks whether they are part of the Plaid Network and verifies that they meet your onboarding requirements. Plaid Layer then authenticates the device and performs real-time risk analysis to reduce the risk of fraudulent sign-up attempts. After the user confirms their details and decides which financial account they want to share, you can verify their identity using your KYC provider and connect their accounts with Plaid. The user enters their phone number within your application. (An image of "The user enters their phone number within your application.") (An image of "Plaid determines the user is eligible for Layer, so they are prompted to continue with Plaid.") (An image of "The user's device is authenticated...") (An image of "...and the user chooses what information to share with your application.") (An image of "And we're done! You're now able to retrieve user account data.") To get started with Layer, [contact sales](https://plaid.com/layer/#contact-form) to request Sandbox access. [See a live, interactive demo](https://plaid.coastdemo.com/share/6717daecf618361b93d583f5?zoom=100) of a Plaid-powered onboarding flow using Layer. #### Integration overview  If you use Layer with Consumer Report or other Plaid Check Products, see the [Plaid Check / Layer onboarding guide](https://plaid.com/docs/check/onboard-users-with-layer/index.html.md) . [Prefer to learn by watching? Check out this quick video guide to implementing Layer with Extended Autofill](https://www.youtube.com/watch?v=vMo6VyJSWeg) 1. Configure a Layer template via the [Dashboard](https://dashboard.plaid.com/layer) . A template is created by default on first visit. You can customize the template's name, set logo and colors to match your brand, and configure eligibility requirements. In general, fill rates for different user data identity fields are highly correlated with each other (i.e., if Plaid has access to one piece of user identity information, it very likely has access to all of them), so you should set "required" and "optional" eligibility requirements based on your true business needs. For a detailed tour of the available Layer template configuration options, see the [Layer Dashboard video walkthrough](https://www.youtube.com/watch?v=5vYFAsfEaqM) . 2. Call [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) with the template ID for the Layer template you configured. This will return a `link` object that contains a `link_token`. 3. On your client, create an instance of Link using the `link.link_token` string returned by [/session/token/create](https://plaid.com/docs/api/products/layer/index.html.md#sessiontokencreate) . With Layer, you should create the Plaid handler object (i.e. via `Plaid.create(...)`) as early as possible so Link can pre-load in the background. This ensures the fastest possible experience for your users. If you have an existing Android integration that does not use a `PlaidHandler` or that uses `OpenPlaidLink` instead of `FastOpenPlaidLink`, or an existing React Native integration that uses `PlaidLink` instead of `create` and `open`, you will need to update your client-side Link opening code to take advantage of the new faster loading scheme. For details and sample code, see [React Native: opening Link](https://plaid.com/docs/link/react-native/index.html.md#opening-link) and [Android: opening Link](https://plaid.com/docs/link/android/index.html.md#create-a-linktokenconfiguration) . 4. Once you have a user's phone number, pass it to the Plaid handler object: `handler.submit({ "phone_number": "+14155550015"})`. Link will quickly check if the user is eligible for Layer, and call the Link `onEvent` callback with either `LAYER_READY` or `LAYER_NOT_AVAILABLE`. Note that if the phone number uses a country code other than +1, the result will always be `LAYER_NOT_AVAILABLE`, as Layer does not support international phone numbers. 5. When you receive `LAYER_READY`, it means the user is eligible and you should call `handler.open()` to immediately present the Layer UI. 6. (Optional, recommended) If you receive `LAYER_NOT_AVAILABLE` instead, collect the user's date of birth and `submit` it via the same handler as earlier, e.g. `handler.submit({ "date_of_birth": "1975-01-18"})`. If you receive `LAYER_READY`, the user is eligible for [Layer Extended Autofill](https://plaid.com/docs/layer/index.html.md#extended-autofill) and you should call `handler.open()` to immediately present the Layer UI; the flow continues at step 8. If you receive `LAYER_AUTOFILL_NOT_AVAILABLE`, the flow continues with the next step. 7. If neither Layer nor Layer Extended Autofill are available, you may discard the handler object and continue with any non-Layer flow in your app. For example, if your application falls back to a non-Layer product flow, you'd create a new Link token and handler to present that flow. If your non-Layer flow involves creating a Link token, include the `phone_number` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) for a faster end user experience. 8. After you have launched the Layer flow in Link via `handler.open()`, the end user enters the Layer flow. You will receive a [LAYER\_AUTHENTICATION\_PASSED](https://plaid.com/docs/api/products/layer/index.html.md#layer_authentication_passed) webhook once Plaid has determined that the end user has demonstrated ownership of the phone number, via either OTP or SNA. If the end user does not fully complete the Link flow but you receive this webhook, you can skip any OTP phone number verification steps you would otherwise implement. 9. Once the end user has successfully completed the Layer flow in Link, you will receive an `onSuccess` callback and a [SESSION\_FINISHED](https://plaid.com/docs/api/products/layer/index.html.md#session_finished) webhook, both of which contain the `public_token`. Use the received `public_token` with the [/user\_account/session/get](https://plaid.com/docs/api/products/layer/index.html.md#user_accountsessionget) API in order to retrieve the user's profile information and any linked Items. #### Sample code  For a walkthrough of integrating Layer, including sample code across multiple platforms, see [Add Layer to your app](https://plaid.com/docs/layer/add-to-app/index.html.md) . #### Minimum SDK versions  As Plaid is actively adding new Layer functionality, it is strongly recommended that you use the latest SDK version and keep up to date with SDK updates if your app uses Layer. If you are developing for the web using the JavaScript SDK, Plaid will automatically provide the latest available SDK. Otherwise, see [libraries](https://plaid.com/docs/api/libraries/index.html.md#link-client-sdks) for links to the latest SDKs. If you are developing a native mobile application, Layer requires SDK versions from June 2024 or later. Minimum versions are 6.0.4 (iOS), 4.5.0 (Android), 11.11.0 (React Native), and 3.5.2 (React). For Extended Autofill support, minimum versions are 6.3.1 (iOS), 5.3.0 (Android), 12.4.0 (React Native), and 4.1.1 (React). Layer is not compatible with the [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) integration mode. #### Extended Autofill  Extended Autofill allows you to use the user's date of birth as a fallback for autofilling their identity data if their phone number is not Layer eligible. For Extended Autofill support, minimum SDK versions are 6.3.1 (iOS), 5.3.0 (Android), 12.4.0 (React Native), and 4.1.1 (React). To use Extended Autofill, after receiving `LAYER_NOT_AVAILABLE`, submit the date of birth, e.g. `handler.submit({ "date_of_birth": "1975-01-18"})`. This must be in a separate call, made only after calling `submit` with the user's phone number. You will get either a `LAYER_READY` callback (success) or a `LAYER_AUTOFILL_NOT_AVAILABLE` callback (failure). Extended Autofill is still subject to the same eligibility requirements that you defined in your Layer template. You may wish to make **Collect financial accounts** "Optional" instead of "Required" in your eligibility requirements, as Extended Autofill users are less likely to have connected account information. When using Extended Autofill, in order to reduce onboarding friction, it is strongly recommended to prompt the user for their date of birth only after receiving `LAYER_NOT_AVAILABLE`, rather than requesting it upfront. #### Intelligent Account Sorting  By default, Layer orders accounts in Link based on which one is likeliest to have the highest conversion. With Intelligent Account Sorting, you can instead prioritize either the highest-balance account or the account that Plaid detects as being the user's primary bank account. The prioritized account will have a "Recommended" badge displayed next to it in Link. Intelligent Account Sorting may be a good fit for customers are using Layer in flows for cashflow underwriting, EWA, or cash advance. To enable Intelligent Account Sorting, contact your Plaid account manager, and specify which prioritization scheme (primary account or highest balance account) you prefer and which Link customizations the scheme should be applied to. #### Testing Layer  In Sandbox, the authentication code for all phone numbers is `123456`. The basic test phone number is `415-555-0011`, which will connect to a standard profile with full PII and two connected banks. The date of birth (for Extended Autofill testing) is `1975-01-18`. The following phone numbers are all valid in Sandbox for Layer testing: | Phone number | Notes | | --- | --- | | 415-555-0000 | Missing all identity and bank data | | 415-555-0011 | Default number for testing | | 415-555-0012 | Missing PII; 3 connected banks | | 415-555-0015 | Standard profile with a single bank | | 515-555-0013 | Missing email | | 515-555-0015 | Missing DOB | | 515-555-0016 | Missing SSN | | 515-555-0017 | Missing address | | 515-555-0018 | Missing name | | 515-555-0019 | Standard profile, but savings account only | Note the area code is not the same in all of these test numbers. In Production, the authentication step of Layer is dynamic and may authenticate the user via Silent Network Authentication, SMS OTP, or Passkeys (coming soon), depending on the user and the device; authentication checks such as trusted device matching or mobile carrier checks (for SIM swaps, port outs, etc.) are also run in Production. Sandbox provides a simplified authentication experience: in Sandbox, users can only be authenticated via OTP, and authentication checks are not run. ##### Testing Layer with custom Sandbox users  To test Layer with specific combinations of account types, transactions, or other data, you can create a [custom Sandbox user](https://plaid.com/docs/sandbox/user-custom/index.html.md) . To use this user in Layer: * After launching Layer with an eligible phone number, on the Confirm details pane, click the edit button (the pencil icon) next to the **Bank Account** entry. * Then select **Add new account** * From there, complete the flow, logging in as your custom Sandbox user. * When you complete Link and make API calls, you will see the custom Sandbox data you seeded. ##### Testing Extended Autofill  To test Extended Autofill, you can follow one of two different scenarios: * Submit any phone number that fails Layer eligibility completely, like `415-555-0000`, with a template that specifies **Collect financial accounts** as Optional or Skip. The user will be eligible for Extended Autofill, and you will receive a full set of identity information. * Submit any of the phone numbers above that are missing some identity information (such as `515-555-0017`) while using a Layer template that requires that information. The user will not initially be eligible for Layer, but they will be eligible for Extended Autofill, because it will fill in the missing gaps in the user data. In this scenario, you will receive a full set of identity information and a connected bank account. In both cases, submit `1975-01-18` for the user's date of birth. #### Layer webhooks  Layer has the following webhooks: | Event | Meaning | | --- | --- | | [LAYER\_AUTHENTICATION\_PASSED](https://plaid.com/docs/api/products/layer/index.html.md#layer_authentication_passed) | A user has been authenticated | | [SESSION\_FINISHED](https://plaid.com/docs/api/products/layer/index.html.md#session_finished) | A Layer session has finished | #### Layer events  In addition to the standard Link events, Layer has the following events: | Event | Meaning | | --- | --- | | `LAYER_READY` | Plaid found data matching template requirements; call `handler.open()` to present Layer | | `LAYER_NOT_AVAILABLE` | No data found matching template requirements based on the phone number; prompt for date of birth or use non-Layer flow | | `LAYER_AUTOFILL_NOT_AVAILABLE` | No data found matching template requirements based on the phone number + date of birth; use non-Layer flow | | `SUBMIT_OTP` | User has entered an OTP code to verify their phone number (also used by Returning User Experience) | | `VERIFY_PHONE` | User has successfully verified their phone number (also used by Returning User Experience) | For a full list of events, see the [Link onEvent documentation](https://plaid.com/docs/link/web/index.html.md#onevent) . ##### Example event sequences  The sections below illustrate typical frontend event sequences for different Layer scenarios. For more details on frontend events, see the [Link onEvent documentation](https://plaid.com/docs/link/web/index.html.md#onevent) . Events for successful Layer flow, verified via SNA ```json LAYER_READY OPEN TRANSITION_VIEW: CONSENT TRANSITION_VIEW: VERIFY_PHONE TRANSITION_VIEW: PROFILE_DATA_REVIEW VERIFY_PHONE HANDOFF (with onSuccess callback) ``` Events for failed Layer flow, end user entered OTP incorrectly three times ```json LAYER_READY OPEN TRANSITION_VIEW: CONSENT TRANSITION_VIEW: VERIFY_PHONE SUBMIT_OTP ERROR: INVALID_OTP SUBMIT_OTP ERROR: INVALID_OTP SUBMIT_OTP TRANSITION_VIEW: ERROR ERROR: PROFILE_AUTHENTICATION_FAILED EXIT (with onExit callback) ``` Events for Layer-ineligible flow ```json LAYER_NOT_AVAILABLE LAYER_AUTOFILL_NOT_AVAILABLE ``` #### Measuring conversion  To track Layer performance, measure the following ratios: **Layer eligibility percentage**: `LAYER_READY` event count / `handler.submit(phone_number)` count. Ensure you do not count `handler.submit` calls for date of birth. **Layer conversion**: `onSuccess` callback count (or `HANDOFF` event count) / `OPEN` event count #### Billing  When using Layer, a billing event is incurred for each converted Link session (when `onSuccess` fires). You will not be billed for Layer eligibility checks or unconverted Layer sessions. #### Launch checklist  Recommended steps to take before launching in Production [Launch](https://plaid.com/docs/launch-checklist/index.html.md) --- # Liabilities - Add Liabilities to your app | Plaid Docs Add Liabilities to your app  ============================ #### Use Liabilities to fetch data for credit, student loan, and mortgage accounts  In this guide, we'll start from scratch and walk through how to use Liabilities to retrieve information about credit card, PayPal credit, student loan, and mortgage accounts. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, make sure to initialize Link with the `liabilities` product and to note that Liabilities supports the use of [account subtype filtering](https://plaid.com/docs/liabilities/add-to-app/index.html.md#create-an-item-in-link) ; you can then skip ahead to [Fetching Liabilities data](https://plaid.com/docs/liabilities/add-to-app/index.html.md#fetching-liabilities-data) . #### Get Plaid API keys and complete application profile  If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Team Settings menu on the Plaid Dashboard. You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile must be completed before connecting to certain institutions in Production. #### Install and initialize Plaid libraries  You can use our official server-side client libraries to connect to the Plaid API from your application: ```node // Install via npm npm install --save plaid ``` ```bash ## Not applicable with curl calls ``` ```ruby # Available as a gem gem install plaid ``` ```java /* For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ implementation "com.plaid:plaid-java:{VERSION}" /* For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from - https://github.com/plaid/plaid-java/releases/latest */ com.plaid plaid-java {VERSION} ``` ```python # Install through pip, only supports Python 3 pip install --upgrade plaid-python ``` ```go go get github.com/plaid/plaid-go ``` After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls. ```node // Using Express const express = require('express'); const app = express(); app.use(express.json()); const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid'); const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, baseOptions: { headers: { 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID, 'PLAID-SECRET': process.env.PLAID_SECRET, }, }, }); const client = new PlaidApi(configuration); ``` ```bash ## Not applicable with curl calls ``` ```ruby require 'sinatra' require 'plaid' set :port, ENV['APP_PORT'] || 8000 configuration = Plaid::Configuration.new configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox'] configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID'] configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET'] api_client = Plaid::ApiClient.new( configuration ) client = Plaid::PlaidApi.new(api_client) ``` ```java import java.net.*; import java.io.*; import retrofit2.Response; import java.util.Arrays; import com.sun.net.httpserver.*; import com.plaid.client.ApiClient; import com.plaid.client.request.PlaidApi; public class PlaidExample { private static final String CLIENT_ID = System.getenv("PLAID_CLIENT_ID"); private static final String SECRET = System.getenv("PLAID_SECRET"); public static void main(String[] args) { HttpServer server = HttpServer.create( new InetSocketAddress("localhost", 8000), 0); server.createContext("/create_link_token", new GetLinkToken()); server.setExecutor(null); server.start(); } // Additional server code goes here } ``` ```python import plaid from plaid.api import plaid_api from flask import Flask from flask import render_template from flask import request from flask import jsonify app = Flask(name) configuration = plaid.Configuration( host=plaid.Environment.Sandbox, api_key={ 'clientId': PLAID_CLIENT_ID, 'secret': PLAID_SECRET, } ) api_client = plaid.ApiClient(configuration) client = plaid_api.PlaidApi(api_client) # Additional server code goes here if __name__ == "__main__": app.run(port=8000) ``` ```go import ( "context" "net/http" "os" "github.com/gin-gonic/gin" "github.com/plaid/plaid-go/v3/plaid" ) configuration := plaid.NewConfiguration() configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID")) configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET")) configuration.UseEnvironment(plaid.Sandbox) client := plaid.NewAPIClient(configuration) func main() { r := gin.Default() // Server endpoints would be declared here // e.g. r.POST("/create_link_token", createLinkToken) r.POST("/create_link_token", createLinkToken) err := r.Run(":8000") if err != nil { panic("unable to start server") } } ``` #### Create an Item in Link  Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) . Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. First, on the client side of your application, you'll need to set up and configure Link. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) . When initializing Link, you will need to specify the products you will be using in the product array. Liabilities supports the use of the `account_filters` parameter to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , which you can use to limit the account types that will be shown in Link to either only credit card accounts, only student loan accounts, or only mortgage accounts. For student loans, use the type `loan` and subtype `student`. For credit cards, use the type `credit` and subtype `credit card`. For mortgages, use the type `loan` and subtype `mortgage`. ##### Create a link\_token  ```node app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['liabilities'], language: 'en', webhook: 'https://webhook.example.com', redirect_uri: 'https://domainname.com/oauth-page.html', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "products": ["liabilities"], "country_codes": ["US"], "language": "en", "webhook": "https://webhook.example.com", "redirect_uri": "https://domainname.com/oauth-page.html" }' ``` ```ruby post '/api/create_link_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: client_user_id }, client_name: 'Plaid Test App', products: ['liabilities'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.example.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.Products; import com.plaid.client.model.CountryCode; import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; public class PlaidExample { ... static class GetLinkToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.fromValue("liabilities"))) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .redirectUri("https://domainname.com/oauth-page.html") .webhook("https://webhook.example.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.link_token_create_request import LinkTokenCreateRequest from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser from plaid.model.products import Products from plaid.model.country_code import CountryCode @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( products=[Products("liabilities")], client_name="Plaid Test App", country_codes=[CountryCode('US')], redirect_uri='https://domainname.com/oauth-page.html', language='en', webhook='https://webhook.example.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetRedirectUri("https://domainname.com/oauth-page.html") request.SetProducts([]plaid.Products{plaid.PRODUCTS_LIABILITIES}) resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` ##### Install Link dependency  index.html ```html Connect a bank ``` ##### Configure the client-side Link handler  app.js ```javascript const linkHandler = Plaid.create({ token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token to your app server. $.post('/exchange_public_token', { public_token: public_token, }); }, onExit: (err, metadata) => { // Optionally capture when your user exited the Link flow. // Storing this information can be helpful for support. }, onEvent: (eventName, metadata) => { // Optionally capture Link flow events, streamed through // this callback as your users connect an Item to Plaid. }, }); linkHandler.open(); ``` #### Get a persistent access\_token  Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call. Save the `access_token` and `item_id` in a secure datastore, as they're used to access `Item` data and identify `webhooks`, respectively. The `access_token` will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it. ```node app.post('/api/exchange_public_token', async function ( request, response, next, ) { const publicToken = request.body.public_token; try { const tokenResponse = await client.itemPublicTokenExchange({ public_token: publicToken, }); // These values should be saved to a persistent database and // associated with the currently signed-in user const accessToken = tokenResponse.data.access_token; const itemID = tokenResponse.data.item_id; response.json({ public_token_exchange: 'complete' }); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/item/public_token/exchange \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "public_token": "public-sandbox-12345678-abcd-1234-abcd-1234567890ab" }' ``` ```ruby access_token = nil post '/api/exchange_public_token' do request = Plaid::ItemPublicTokenExchangeRequest.new( { public_token: params["public_token"] } ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response.access_token item_id = response.item_id content_type :json {public_token_exchange: "complete"}.to_json end ``` ```java import com.plaid.client.model.ItemPublicTokenExchangeRequest; import com.plaid.client.model.ItemPublicTokenExchangeResponse; public class PlaidExample { ... static class GetAccessToken implements HttpHandler { private static PlaidClient plaidClient; private String publicToken; private String accessToken; private String itemId; public void handle(HttpExchange t) throws IOException { // Simplified pseudo-code for obtaining public_token InputStream is = t.getRequestBody(); publicToken = is.publicToken(); // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); apiKeys.put("plaidVersion", "2020-09-14"); apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Exchange public_token for an access_token ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest() .publicToken(publicToken); Response response = plaidClient .itemPublicTokenExchange(request) .execute(); // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken = response.body().getAccessToken(); itemId = response.body().getItemId(); String message = "{\"public_token_exchange\": \"complete\"}"; return Response .status(Response.Status.OK) .entity(message) .type(MediaType.APPLICATION_JSON) } } } ``` ```python access_token = None item_id = None @app.route('/exchange_public_token', methods=['POST']) def exchange_public_token(): global access_token public_token = request.form['public_token'] request = ItemPublicTokenExchangeRequest( public_token=public_token ) response = client.item_public_token_exchange(request) # These values should be saved to a persistent database and # associated with the currently signed-in user access_token = response['access_token'] item_id = response['item_id'] return jsonify({'public_token_exchange': 'complete'}) ``` ```go func getAccessToken(c *gin.Context) { ctx := context.Background() publicToken := c.PostForm("public_token") // exchange the public_token for an access_token exchangePublicTokenReq := plaid.NewItemPublicTokenExchangeRequest(publicToken) exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest( *exchangePublicTokenReq, ).Execute() // These values should be saved to a persistent database and // associated with the currently signed-in user accessToken := exchangePublicTokenResp.GetAccessToken() itemID := exchangePublicTokenResp.GetItemId() c.JSON(http.StatusOK, gin.H{"public_token_exchange": "complete"}) } ``` #### Fetching Liabilities data  Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API. For more detailed information on the schema for account information returned, see [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) . ```bash curl -X POST https://sandbox.plaid.com/liabilities/get \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "access_token": String }' ``` ```node const { LiabilitiesGetRequest } = require('plaid'); // Retrieve Liabilities data for an Item const request: LiabilitiesGetRequest = { access_token: accessToken, }; try { const response = await plaidClient.liabilitiesGet(request); const liabilities = response.data.liabilities; } catch (error) { // handle error } ``` ```python import plaid from plaid.model.liabilities_get_request import LiabilitiesGetRequest # retrieve Liabilities data for an item request = LiabilitiesGetRequest(access_token=access_token) response = client.liabilities_get(request) liabilities = response['liabilities'] ``` ```java import com.plaid.client.model.LiabilitiesGetRequest; import com.plaid.client.model.LiabilitiesGetResponse; import com.plaid.client.model.LiabilitiesObject; // Retrieve Liabilities data for an Item LiabilitiesGetRequest request = new LiabilitiesGetRequest() .accessToken(accessToken); Response response = client() .liabilitiesGet(request) .execute(); LiabilitiesObject liabilities = response.body().getLiabilities(); List liabilitiesStreams = liabilities.getLiabilitiesStreams(); ``` ```ruby require 'plaid' # retrieve Liabilities data for an item request = Plaid::LiabilitiesGetRequest.new({ access_token: access_token }) response = client.liabilities_get(request) liabilities = response.liabilities ``` ```go import ( "context" "github.com/plaid/plaid-go/v40/plaid" ) request := plaid.NewLiabilitiesGetRequest(accessToken) resp, _, err := client.PlaidApi.LiabilitiesGet(ctx).LiabilitiesGetRequest(*request).Execute() ``` Example response data is below. The data provided is for illustrative purposes; in a Production environment, it would be very unusual for a single institution to provide both credit card and student loan data. Liabilities sample response ```json { "accounts": [ { "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp", "balances": { "available": 100, "current": 110, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "0000", "name": "Plaid Checking", "official_name": "Plaid Gold Standard 0% Interest Checking", "subtype": "checking", "type": "depository" }, { "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "balances": { "available": null, "current": 410, "iso_currency_code": "USD", "limit": 2000, "unofficial_currency_code": null }, "mask": "3333", "name": "Plaid Credit Card", "official_name": "Plaid Diamond 12.5% APR Interest Credit Card", "subtype": "credit card", "type": "credit" }, { "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE", "balances": { "available": null, "current": 65262, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "7777", "name": "Plaid Student Loan", "official_name": null, "subtype": "student", "type": "loan" }, { "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J", "balances": { "available": null, "current": 56302.06, "iso_currency_code": "USD", "limit": null, "unofficial_currency_code": null }, "mask": "8888", "name": "Plaid Mortgage", "official_name": null, "subtype": "mortgage", "type": "loan" } ], "item": { "available_products": ["balance", "credit_details", "investments"], "billed_products": [ "assets", "auth", "identity", "liabilities", "transactions" ], "consent_expiration_time": null, "error": null, "institution_id": "ins_3", "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6", "webhook": "https://www.genericwebhookurl.com/webhook" }, "liabilities": { "credit": [ { "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "aprs": [ { "apr_percentage": 15.24, "apr_type": "balance_transfer_apr", "balance_subject_to_apr": 1562.32, "interest_charge_amount": 130.22 }, { "apr_percentage": 27.95, "apr_type": "cash_apr", "balance_subject_to_apr": 56.22, "interest_charge_amount": 14.81 }, { "apr_percentage": 12.5, "apr_type": "purchase_apr", "balance_subject_to_apr": 157.01, "interest_charge_amount": 25.66 }, { "apr_percentage": 0, "apr_type": "special", "balance_subject_to_apr": 1000, "interest_charge_amount": 0 } ], "is_overdue": false, "last_payment_amount": 168.25, "last_payment_date": "2025-05-22", "last_statement_issue_date": "2025-05-28", "last_statement_balance": 1708.77, "minimum_payment_amount": 20, "next_payment_due_date": "2025-05-28" } ], "mortgage": [ { "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J", "account_number": "3120194154", "current_late_fee": 25.0, "escrow_balance": 3141.54, "has_pmi": true, "has_prepayment_penalty": true, "interest_rate": { "percentage": 3.99, "type": "fixed" }, "last_payment_amount": 3141.54, "last_payment_date": "2025-08-01", "loan_term": "30 year", "loan_type_description": "conventional", "maturity_date": "2045-07-31", "next_monthly_payment": 3141.54, "next_payment_due_date": "2025-11-15", "origination_date": "2015-08-01", "origination_principal_amount": 425000, "past_due_amount": 2304, "property_address": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "ytd_interest_paid": 12300.4, "ytd_principal_paid": 12340.5 } ], "student": [ { "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE", "account_number": "4277075694", "disbursement_dates": ["2002-08-28"], "expected_payoff_date": "2032-07-28", "guarantor": "DEPT OF ED", "interest_rate_percentage": 5.25, "is_overdue": false, "last_payment_amount": 138.05, "last_payment_date": "2025-04-22", "last_statement_issue_date": "2025-04-28", "loan_name": "Consolidation", "loan_status": { "end_date": "2032-07-28", "type": "repayment" }, "minimum_payment_amount": 25, "next_payment_due_date": "2025-05-28", "origination_date": "2002-08-28", "origination_principal_amount": 25000, "outstanding_interest_amount": 6227.36, "payment_reference_number": "4277075694", "pslf_status": { "estimated_eligibility_date": "2028-01-01", "payments_made": 200, "payments_remaining": 160 }, "repayment_plan": { "description": "Standard Repayment", "type": "standard" }, "sequence_number": "1", "servicer_address": { "city": "San Matias", "country": "US", "postal_code": "99415", "region": "CA", "street": "123 Relaxation Road" }, "ytd_interest_paid": 280.55, "ytd_principal_paid": 271.65 } ] }, "request_id": "dTnnm60WgKGLnKL" } ``` #### Set up webhook listener  To be alerted to changes in Liabilities data, listen for the [DEFAULT\_UPDATE](https://plaid.com/docs/api/products/liabilities/index.html.md#default_update) webhook. Upon receiving this webhook, you can call [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) again to retrieve updated liabilities information. #### Next steps  If you're ready to launch to Production, see the Launch checklist. #### Launch checklist  Recommended steps to take before launching in Production [Launch](https://plaid.com/docs/launch-checklist/index.html.md) --- # Liabilities - Introduction to Liabilities | Plaid Docs Introduction to Liabilities   ============================= #### Access data for private student loans, mortgages, and credit cards  Get started with Liabilities [API Reference](https://plaid.com/docs/api/products/liabilities/index.html.md) [Quickstart](https://plaid.com/docs/quickstart/index.html.md) #### Overview  Plaid's Liabilities product allows you to access information about a user's debts. A common application is personal financial management tools to help customers manage or refinance debt. Liabilities is supported in the US and Canada (Canada coverage is limited). #### Liabilities data  With Liabilities, you can view account information for credit cards, PayPal credit accounts, private student loans, and mortgages in the US. Available information includes balance, next payment date and amount, loan terms such as duration and interest rate, and originator information such as the origination date and initial loan amount. Liabilities data is refreshed approximately once per day, and the latest data can be accessed by calling [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) . Note that liabilities data does not contain detailed transaction history for credit card accounts. For credit card account transactions, use the [Transactions](https://plaid.com/docs/transactions/index.html.md) product. Sample Liabilities data: credit card account ```json "credit": [ { "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK", "aprs": [ { "apr_percentage": 15.24, "apr_type": "balance_transfer_apr", "balance_subject_to_apr": 1562.32, "interest_charge_amount": 130.22 }, { "apr_percentage": 27.95, "apr_type": "cash_apr", "balance_subject_to_apr": 56.22, "interest_charge_amount": 14.81 }, { "apr_percentage": 12.5, "apr_type": "purchase_apr", "balance_subject_to_apr": 157.01, "interest_charge_amount": 25.66 }, { "apr_percentage": 0, "apr_type": "special", "balance_subject_to_apr": 1000, "interest_charge_amount": 0 } ], "is_overdue": false, "last_payment_amount": 168.25, "last_payment_date": "2019-05-22", "last_statement_issue_date": "2019-05-28", "last_statement_balance": 1708.77, "minimum_payment_amount": 20, "next_payment_due_date": "2020-05-28" } ] ``` Sample Liabilities data: student loan account ```json "student": [ { "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE", "account_number": "4277075694", "disbursement_dates": [ "2002-08-28" ], "expected_payoff_date": "2032-07-28", "guarantor": "DEPT OF ED", "interest_rate_percentage": 5.25, "is_overdue": false, "last_payment_amount": 138.05, "last_payment_date": "2019-04-22", "last_statement_issue_date": "2019-04-28", "loan_name": "Consolidation", "loan_status": { "end_date": "2032-07-28", "type": "repayment" }, "minimum_payment_amount": 25, "next_payment_due_date": "2019-05-28", "origination_date": "2002-08-28", "origination_principal_amount": 25000, "outstanding_interest_amount": 6227.36, "payment_reference_number": "4277075694", "pslf_status": { "estimated_eligibility_date": "2021-01-01", "payments_made": 200, "payments_remaining": 160 }, "repayment_plan": { "description": "Standard Repayment", "type": "standard" }, "sequence_number": "1", "servicer_address": { "city": "San Matias", "country": "US", "postal_code": "99415", "region": "CA", "street": "123 Relaxation Road" }, "ytd_interest_paid": 280.55, "ytd_principal_paid": 271.65 } ] ``` Sample Liabilities data: mortgage account ```json "mortgage": [ { "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J", "account_number": "3120194154", "current_late_fee": 25.0, "escrow_balance": 3141.54, "has_pmi": true, "has_prepayment_penalty": true, "interest_rate": { "percentage": 3.99, "type": "fixed" }, "last_payment_amount": 3141.54, "last_payment_date": "2019-08-01", "loan_term": "30 year", "loan_type_description": "conventional", "maturity_date": "2045-07-31", "next_monthly_payment": 3141.54, "next_payment_due_date": "2019-11-15", "origination_date": "2015-08-01", "origination_principal_amount": 425000, "past_due_amount": 2304, "property_address": { "city": "Malakoff", "country": "US", "postal_code": "14236", "region": "NY", "street": "2992 Cameron Road" }, "ytd_interest_paid": 12300.4, "ytd_principal_paid": 12340.5 } ] ``` #### Payment history  The information returned by a [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) request contains recent payment information, such as the date and amount of the most recent payment. To view further payment history, you can use Plaid's [Transactions](https://plaid.com/docs/transactions/index.html.md) product. #### Liabilities webhooks  Plaid checks for updated Liabilities data approximately once per day and uses webhooks to inform you of any changes so you can keep your app up to date. For more detail on how to listen and respond to these webhooks, see [Liabilities webhooks](https://plaid.com/docs/api/products/liabilities/index.html.md#webhooks) . #### Testing Liabilities  Liabilities can be tested in Sandbox without any additional permissions. Plaid also provides a [GitHub repo](https://github.com/plaid/sandbox-custom-users/) with test data for testing student loan accounts in Sandbox. For more information on configuring custom Sandbox data, see [Configuring the custom user account](https://plaid.com/docs/sandbox/user-custom/index.html.md#configuring-the-custom-user-account) . #### Liabilities pricing  Liabilities is billed on a [subscription model](https://plaid.com/docs/account/billing/index.html.md#subscription-fee) . To view the exact pricing you may be eligible for, [apply for Production access](https://dashboard.plaid.com/overview/production) or [contact sales](https://plaid.com/contact/) . For more details about pricing and billing models, see [Plaid billing](https://plaid.com/docs/account/billing/index.html.md) . #### Next steps  To get started building with Liabilities, see [Add Liabilities to your App](https://plaid.com/docs/liabilities/add-to-app/index.html.md) . If you're ready to launch to Production, see the Launch checklist. #### Launch Center  See next steps to launch in Production [Launch](https://dashboard.plaid.com/developers/launch-center) --- # Link - Android | Plaid Docs Link Android SDK  ================= #### Learn how to integrate your app with the Link Android SDK  #### Overview  The Plaid Link SDK is a quick and secure way to link bank accounts to Plaid in your Android app. Link is a drop-in module that handles connecting a financial institution to your app (credential validation, multi-factor authentication, error handling, etc.), without passing sensitive personal information to your server. To get started with Plaid Link for Android, clone the [GitHub repository](https://github.com/plaid/plaid-link-android) and try out the example application, which provides a reference implementation in both Java and Kotlin. Youʼll want to sign up for [free API keys](https://dashboard.plaid.com/developers/keys) through the Plaid Dashboard to get started. Prefer to learn by watching? A [video guide](https://youtu.be/oM7vL49I5tc) is available for this content. #### Initial Android setup  Before writing code using the SDK, you must first perform some setup steps to register your app with Plaid and configure your project. ##### Register your app ID  To register your Android app ID: 1. Sign in to the [Plaid Dashboard](https://dashboard.plaid.com/signin) and go to the [Developers -> API](https://dashboard.plaid.com/developers/api) page. 2. Next to **Allowed Android Package Names** click **Configure** then **Add New Android Package Name**. 3. Enter your package name, for example `com.plaid.example`. 4. Click **Save Changes**. Your Android app is now set up and ready to start integrating with the Plaid SDK. New versions of the Android SDK are released frequently, at least once every few months. Major releases occur annually. You should keep your version up-to-date to provide the best Plaid Link experience in your application. ##### Update your project plugins  In your root-level (project-level) Gradle file (`build.gradle`), add rules to include the Android Gradle plugin. Check that you have Google's Maven repository as well. build.gradle (Project-level) ```groovy buildscript { repositories { // Check that you have the following line (if not, add it): google() // Google's Maven repository mavenCentral() // Include to import Plaid Link Android SDK } dependencies { // ... } } ``` ##### Add the PlaidLink SDK to your app  In your module (app-level) Gradle file (usually `app/build.gradle`), add a line to the bottom of the file. The latest version of the PlaidLink SDK is (An image of "Maven Central") and can be found on [Maven Central](https://search.maven.org/artifact/com.plaid.link/sdk-core) . build.gradle (App-level) ```kotlin android { defaultConfig { minSdkVersion 21 // or greater } } dependencies { // ... implementation 'com.plaid.link:sdk-core:' } ``` ##### Enable camera support (Identity Verification only)  If your app uses [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) , a user may need to take a picture of identity documentation or a selfie during the Link flow. To support this workflow, the [CAMERA](https://developer.android.com/reference/android/Manifest.permission#CAMERA) , [WRITE\_EXTERNAL\_STORAGE](https://developer.android.com/reference/android/Manifest.permission#WRITE_EXTERNAL_STORAGE) , [RECORD\_AUDIO](https://developer.android.com/reference/android/Manifest.permission#RECORD_AUDIO) , and [MODIFY\_AUDIO\_SETTINGS](https://developer.android.com/reference/android/Manifest.permission#MODIFY_AUDIO_SETTINGS) permissions need to be added to your application's `AndroidManifest.xml`. (While Plaid does not record any audio, some older Android devices require these last two permissions to use the camera.) The `WRITE_EXTERNAL_STORAGE` permission should be limited to < Android 9 (i.e. maxSdk=28). If these permissions are not granted in an app that uses Identity Verification, the app may crash during Link. #### Opening Link  Before you can open Link, you need to first create a `link_token` by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) from your backend. This call should **never** happen directly from the mobile client, as it risks exposing your API secret. The [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call must include the `android_package_name` parameter, which should match the `applicationId` from your app-level `build.gradle` file. You can learn more about `applicationId` in Google's [Android developer documentation](https://developer.android.com/studio/build/application-id) . ```ruby link_token_create_request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: "user-id", }, client_name: 'Plaid Test App', products: ['auth'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.sample.com', link_customization_name: "default", android_package_name: "com.plaid.example" } ) response = client.link_token_create( link_token_create_request ) link_token = response.link_token ``` ```go ctx := context.Background() user := plaid.LinkTokenCreateRequestUser{ ClientUserId: "USER_ID_FROM_YOUR_DB", } request := plaid.NewLinkTokenCreateRequest( "Plaid Test", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, user, ) request.SetProducts([]plaid.Products{plaid.PRODUCTS_AUTH}) request.SetLinkCustomizationName("default") request.SetWebhook("https://webhook-uri.com") request.SetAndroidPackageName("com.plaid.example") resp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() linkToken := resp.GetLinkToken() ``` ```java String clientUserId = "user-id"; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId) .legalName("legal name") .phoneNumber("4155558888") .emailAddress("email@address.com"); LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.AUTH)) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .webhook("https://example.com/webhook") .linkCustomizationName("default") .androidPackageName("com.plaid.example") Response response = client() .linkTokenCreate(request) .execute(); String linkToken = response.body().getLinkToken(); ``` ```python request = LinkTokenCreateRequest( products=[Products('auth'), Products('transactions')], client_name="Plaid Test App", country_codes=[CountryCode('GB')], language='en', webhook='https://sample-webhook-uri.com', link_customization_name='default', android_package_name='com.plaid.example', user=LinkTokenCreateRequestUser( client_user_id='123-test-user-id' ) ) # create link token response = client.link_token_create(request) link_token = response['link_token'] ``` ```node const request: LinkTokenCreateRequest = { user: { client_user_id: 'user-id', }, client_name: 'Plaid Test App', products: ['auth', 'transactions'], country_codes: ['GB'], language: 'en', webhook: 'https://sample-web-hook.com', android_package_name: 'com.plaid.example' }; try { const response = await plaidClient.linkTokenCreate(request); const linkToken = response.data.link_token; } catch (error) { // handle error } ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "client_name": "Plaid App", "products": ["auth"], "country_codes": ["GB"], "language": "en", "webhook": "https://sample-web-hook.com", "android_package_name": "com.plaid.example" }' ``` ##### Create a LinkTokenConfiguration  Each time you open Link, you will need to get a new `link_token` from your server and create a new `LinkTokenConfiguration` object with it. ```kotlin val linkTokenConfiguration = linkTokenConfiguration { token = "LINK_TOKEN_FROM_SERVER" } ``` ```java LinkTokenConfiguration linkTokenConfiguration = new LinkTokenConfiguration.Builder() .token("LINK_TOKEN_FROM_SERVER") .build(); ``` The Link SDK runs as a separate `Activity` within your app. In order to return the result to your app, it supports both the standard `startActivityForResult` and `onActivityResult` and the `ActivityResultContract` [result APIs](https://developer.android.com/training/basics/intents/result) . Select group for content switcher Activity Result APIsStandard Activity APIs ##### Register a callback for an Activity Result  ```kotlin private val linkAccountToPlaid = registerForActivityResult(FastOpenPlaidLink()) { when (it) { is LinkSuccess -> /* handle LinkSuccess */ is LinkExit -> /* handle LinkExit */ } } ``` ```java private ActivityResultLauncher linkAccountToPlaid = registerForActivityResult(new FastOpenPlaidLink(), result -> { if (result instanceof LinkSuccess) { /* handle LinkSuccess */ } else { /* handle LinkExit */ } } ); ``` ##### Create a PlaidHandler  Create a `PlaidHandler` - A `PlaidHandler` is a one-time use object used to open a Link session. It should be created as early as possible to warm up Link so that it opens quickly. We recommend doing this as early as possible, since it must be completed before Link opens, and if you create it just before opening Link, it can have a perceptible impact on Link startup time. ```kotlin val plaidHandler: PlaidHandler = Plaid.create(application, linkTokenConfiguration) ``` ```java plaidHandler = Plaid.create(this.getApplication(), linkTokenConfiguration); ``` ##### Open Link  ```kotlin linkAccountToPlaid.launch(plaidHandler) ``` ```java linkAccountToPlaid.launch(plaidHandler); ``` At this point, Link will open, and will trigger the `onSuccess` callback if the user successfully completes the Link flow. \=\*=\*=\*= #### onSuccess  The method is called when a user successfully links an Item. The onSuccess handler returns a `LinkConnection` class that includes the `public_token`, and additional Link metadata in the form of a `LinkConnectionMetadata` class. **Properties** String Displayed once a user has successfully completed Link. If using Identity Verification or Beacon, this field will be `null`. If using Document Income or Payroll Income, the `public_token` will be returned, but is not used. Object Displayed once a user has successfully completed Link. List A list of accounts attached to the connected Item. If Account Select is enabled via the developer dashboard, `accounts` will only include selected accounts. string The Plaid `account_id` string The official account name nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user. LinkAccountSubtype The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values LinkAccountType The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values nullable, string Indicates an Item's micro-deposit-based verification or database verification status. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the deposit. `automatically_verified`: The Item has successfully been automatically verified `manually_verified`: The Item has successfully been manually verified `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `database_matched`: The Item has successfully been verified using Plaid's data sources. `database_insights_pending`: The Database Insights result is pending and will be available upon Auth request. `null`: Neither micro-deposit-based verification nor database verification are being used for the Item. nullable, object An institution object. If the Item was created via Same-Day micro-deposit verification, will be `null`. string The full institution name, such as `'Wells Fargo'` string The Plaid institution identifier nullable, String A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround. nullable, Map The data directly returned from the server with no client side changes. ```kotlin val success = result as LinkSuccess // Send public_token to your server, exchange for access_token // (if using Item-based products) val publicToken = success.publicToken val metadata = success.metadata metadata.accounts.forEach { account -> val accountId = account.id val accountName = account.name val accountMask = account.mask val accountSubType = account.subtype } val institutionId = metadata.institution?.id val institutionName = metadata.institution?.name ``` ```java LinkSuccess success = (LinkSuccess) result; String publicToken = success.getPublicToken(); LinkSuccess.LinkSuccessMetadata metadata = success.getMetadata(); for (LinkAccount account : success.getAccounts()) { String accountId = account.getId(); String accountName = account.getName(); String accountMask = account.getMask(); LinkAccountSubtype accountSubtype = account.getSubtype(); } String institutionId = metadata.getInstitution().getId(); String institutionName = metadata.getInstitution().getName(); ``` \=\*=\*=\*= #### onExit  The `onExit` handler is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The `PlaidError` returned from the `onExit` handler is meant to help you guide your users after they have exited Link. We recommend storing the error and metadata information server-side in a way that can be associated with the user. You’ll also need to include this and any other relevant information in Plaid Support requests for the user. **Properties** Map An object that contains the error type, error code, and error message of the error that was last encountered by the user. If no error was encountered, `error` will be `null`. nullable, String A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. String The particular error code. Each `errorType` has a specific set of `errorCodes`. A code of 499 indicates a client-side exception. String A string representation of the error code. String A broad categorization of the error. String A developer-friendly representation of the error code. nullable, String The data directly returned from the server with no client side changes. Map An object containing information about the exit event nullable, String A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround. nullable, object An institution object. If the Item was created via Same-Day micro-deposit verification, will be `null`. string The full institution name, such as `'Wells Fargo'` string The Plaid institution identifier nullable, String The point at which the user exited the Link flow. One of the following values. User prompted to answer security questions User prompted to answer multiple choice question(s) User prompted to solve a reCAPTCHA challenge User prompted to provide a one-time passcode User prompted to select a device on which to receive a one-time passcode User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution User prompted to select one or more financial accounts to share User exited the Link flow on the institution selection pane. Typically this occurs after the user unsuccessfully (no results returned) searched for a financial institution. Note that this status does not necessarily indicate that the user was unable to find their institution, as it is used for all user exits that occur from the institution selection pane, regardless of other user behavior. User exited the Link flow after discovering their selected institution is no longer supported by Plaid An exit status that is not handled by the current version of the SDK nullable, String The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation ```kotlin val exit = result as LinkExit val error = exit.error error?.let { err -> val errorCode = err.errorCode val errorMessage = err.errorMessage val displayMessage = err.displayMessage } val metadata = exit.metadata val institutionId = metadata.institution?.id val institutionName = metadata.institution?.name val linkSessionId = metadata.linkSessionId; val requestId = metadata.requestId; ``` ```java LinkExit exit = (LinkExit) result; LinkError error = exit.getError(); String errorCode = error.getErrorCode(); String errorMessage = error.getErrorMessage(); String displayMessage = error.getDisplayMessage(); LinkExitMetadata metadata = exit.getMetadata(); String institutionId = metadata.getInstitution().getId(); String institutionName = metadata.getInstitution().getName(); String linkSessionId = metadata.getLinkSessionId(); String requestId = metadata.getRequestId(); ``` \=\*=\*=\*= #### onEvent  The `onEvent` callback is called at certain points in the Link flow. Unlike the handlers for `onSuccess` and `onExit`, the `onEvent` handler is initialized as a global lambda passed to the `Plaid` class. `OPEN`, `LAYER_READY`, `LAYER_NOT_AVAILABLE`, and `LAYER_AUTOFILL_NOT_AVAILABLE` events will be sent in real-time, and remaining events will be sent when the Link session is finished and `onSuccess` or `onExit` is called. Callback ordering is not guaranteed; `onEvent` callbacks may fire before, after, or surrounding the `onSuccess` or `onExit` callback, and event callbacks are not guaranteed to fire in the order in which they occurred. If you need the exact time when an event happened, use the `timestamp` property. The following `onEvent` callbacks are stable, which means that they are suitable for programmatic use in your application's logic: `OPEN`, `EXIT`, `HANDOFF`, `SELECT_INSTITUTION`, `ERROR`, `BANK_INCOME_INSIGHTS_COMPLETED`, `IDENTITY_VERIFICATION_PASS_SESSION`, `IDENTITY_VERIFICATION_FAIL_SESSION`, `LAYER_READY`, `LAYER_NOT_AVAILABLE`, `LAYER_AUTOFILL_NOT_AVAILABLE`. The remaining callback events are informational and subject to change, and should be used for analytics and troubleshooting purposes only. **Properties** String A string representing the event that has just occurred in the Link flow. The user was automatically sent an OTP code without a UI prompt. This event can only occur if the user's phone phone number was provided to Link via the `/link/token/create` call and the user has previously consented to receive OTP codes from Plaid. The user has completed the Assets and Bank Income Insights flow. The user closed the third-party website or mobile app without completing the OAuth flow. The user has chosen to link a new institution instead of linking a saved institution. This event is only emitted in the Link Remember Me flow. A recoverable error occurred in the Link flow, see the `error_code` metadata. The user has exited without completing the Link flow and the [onExit](https://plaid.com#onexit) callback is fired. The user encountered an error while completing the third-party's OAuth login flow. The user has exited Link after successfully linking an Item. An Identity Match check configured via the Account Verification Dashboard failed the Identity Match rules and did not detect a match. An Identity Match check configured via the Account Verification Dashboard passed the Identity Match rules and detected a match. The user has started a step of the Identity Verification flow. The step is indicated by `view_name`. The user has passed a step of the Identity Verification flow. The step is indicated by `view_name`. The user has failed a step of the Identity Verification flow. The step is indicated by `view_name`. The user has reached the pending review state. The user has started a new Identity Verification session. The user has resumed an existing Identity Verification session. The user has passed their Identity Verification session. The user has failed their Identity Verification session. The user has completed their Identity Verification session, which is now in a pending review state. The user has opened the UI of their Identity Verification session. The user has resumed the UI of their Identity Verification session. The user has closed the UI of their Identity Verification session. The user's date of birth passed to Link is not eligible for Layer Extended Autofill. The user phone number passed to Link is not eligible for Layer. The user phone number passed to Link is eligible for Layer and `open()` may now be called. The user selected an institution that was presented as a matched institution. This event can be emitted either during the legacy version of the Returning User Experience flow or if the institution's `routing_number` was provided when calling `/link/token/create`. To distinguish between the two scenarios, see `LinkEventMetadata.match_reason`. The user has opened Link. The user has opened my.plaid.com. This event is only emitted when Link is initialized with Assets as a product. The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow. The user has searched for an institution. The user has opted to not provide their phone number to Plaid. This event is only emitted in the Link Remember Me flow. The user selected a brand, e.g. Bank of America. The `SELECT_BRAND` event is only emitted for large financial institutions with multiple online banking portals. The user selected an institution with a `DEGRADED` health status and was shown a corresponding message. The user selected an institution with a `DOWN` health status and was shown a corresponding message. The user selected an institution Plaid does not support all requested products for and was shown a corresponding message. The user selected an institution. The user has submitted an account number. This event emits the `account_number_mask` metadata to indicate the mask of the account number the user provided. The user has submitted credentials. The user has submitted MFA. The user has submitted an OTP code during the phone number verification flow. This event is only emitted in the Link Returning User Experience (Remember Me) or Layer flow. This event will not be emitted if the phone number is verified via SNA. The user has submitted their phone number. This event is only emitted in the Link Remember Me flow. The user has submitted a routing number. This event emits the `routing_number` metadata to indicate user's routing number. The `TRANSITION_VIEW` event indicates that the user has moved from one view to the next. The user is asked to upload documents (for Income verification). The user has successfully verified their phone number using OTP or SNA. This event is only emitted in the Link Returning User Experience (Remember Me) flow or the Layer flow. The user has viewed data types on the data transparency consent pane. The `UNKNOWN` event indicates that the event is not handled by the current version of the SDK. Map An object containing information about the event. String The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, `account_number_mask` is empty. Emitted by `SUBMIT_ACCOUNT_NUMBER`. String The error code that the user encountered. Emitted by: `ERROR`, `EXIT`. String The error message that the user encountered. Emitted by: `ERROR`, `EXIT`. String The error type that the user encountered. Emitted by: `ERROR`, `EXIT`. String The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT`. String The ID of the selected institution. Emitted by: _all events_. String The name of the selected institution. Emitted by: _all events_. String The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`. String Indicates if the current Link session is an update mode session. Emitted by: `OPEN`. nullable, string The reason this institution was matched. This will be either `returning_user` or `routing_number` if emitted by: `MATCHED_SELECT_INSTITUTION`. Otherwise, this will be `SAVED_INSTITUTION` or `AUTO_SELECT_SAVED_INSTITUTION` if emitted by: `SELECT_INSTITUTION`. Optional The routing number submitted by user at the micro-deposits routing number pane. Emitted by `SUBMIT_ROUTING_NUMBER`. String The `link_session_id` is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: _all events_. String If set, the user has encountered one of the following MFA types: `code` `device` `questions` `selections`. Emitted by: `SUBMIT_MFA` and `TRANSITION_VIEW` when `view_name` is `MFA`. String The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: _all events_. String The Auth Type Select flow type selected by the user. Possible values are `flow_type_manual` or `flow_type_instant`. Emitted by: `SELECT_AUTH_TYPE`. String An ISO 8601 representation of when the event occurred. For example `2017-09-14T14:42:19.350Z`. Emitted by: _all events_. String The name of the view that is being transitioned to. Emitted by: `TRANSITION_VIEW`. The view showing Terms of Service in the identity verification flow. The user has connected their account. We ask the user to consent to the privacy policy. Asking the user for their account credentials. The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor). An error has occurred. Confirming if the user wishes to close Link. The user has authorized an instant micro-deposit to be sent to their account over the RTP or FedNow network with a 3-letter code to verify their account. The view representing the "know your customer" step in the identity verification flow. Link is making a request to our servers. The user is asked by the institution for additional MFA authentication. The user is asked to insert their account and routing numbers. The user goes through the Same Day micro-deposits flow with Reroute to Credentials. The user is informed they will authenticate with the financial institution via OAuth. The user is asked to review their profile data in the Layer flow. The user was presented with a Google reCAPTCHA to verify they are human. The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor). The user has authorized a same day micro-deposit to be sent to their account over the ACH network with a 3-letter code to verify their account. The watchlist screening step in the identity verification flow. We ask the user to choose an account. The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits). The user is asked to select a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals. We ask the user to choose their institution. The user is asked to select their saved accounts and/or new accounts for linking in the Link Returning User Experience (Remember Me) flow. The user is asked to pick a saved institution or link a new one in the Link Remember Me flow. The view in the identity verification flow which uses the camera to confirm there is a real user present that matches their ID documents. The user is asked for their phone number in the Link Returning User Experience (Remember Me) flow. The user is asked to upload documents (for Income verification). The user is asked to verify their phone in the Link Returning User Experience (Remember Me) flow or Layer flow. The SMS verification step in the identity verification flow. nullable, String The data directly returned from the server with no client side changes. ```kotlin Plaid.setLinkEventListener { event -> Log.i("Event", event.toString()) } ``` ```java Plaid.setLinkEventListener(event -> { Log.i("Event", event.toString()); return Unit.INSTANCE; }); ``` \=\*=\*=\*= #### submit()  The `submit` function is currently only used in the Layer product. It allows the client application to submit additional user-collected data to the Link flow (e.g. a user phone number). **Properties** object Data to submit during a Link session. String The end user phone number. String The end user date of birth. To be provided in the format "yyyy-mm-dd". ```kotlin val submissionData = SubmissionData(phoneNumber) plaidHandler.submit(submissionData) ``` ```java SubmissionData submissionData = new SubmissionData(phoneNumber); plaidHandler.submit(submissionData); ``` #### Upgrading  The latest version of the SDK is available from [GitHub](https://github.com/plaid/plaid-link-android) . New versions of the SDK are released frequently. Major releases occur annually. The Link SDK uses Semantic Versioning, ensuring that all non-major releases are non-breaking, backwards-compatible updates. We recommend you update regularly (at least once a quarter, and ideally once a month) to ensure the best Plaid Link experience in your application. SDK versions are supported for two years; with each major SDK release, Plaid will stop officially supporting any previous SDK versions that are more than two years old. While these older versions are expected to continue to work without disruption, Plaid will not provide assistance with unsupported SDK versions. #### Next steps  If you run into problems integrating with Plaid Link on Android, see [Troubleshooting the Plaid Link Android SDK](https://plaid.com/docs/link/android/troubleshooting/index.html.md) . Once you've gotten Link working, see [Link best practices](https://plaid.com/docs/link/best-practices/index.html.md) for recommendations on further improving the Link flow. --- # Link - Troubleshooting | Plaid Docs Troubleshooting the Plaid Link Android SDK  =========================================== #### Enabling Logs  The Link SDK logs information to LogCat at several points in the flow. Pass a `LinkLogLevel` value with the `LinkTokenConfiguration` to see the logs. The levels from least to most verbose: `ERROR`, `WARN`, `INFO`, `DEBUG`, `VERBOSE`. ```kotlin val linkTokenConfiguration = linkTokenConfiguration { token = "LINK_TOKEN_FROM_SERVER" logLevel = if (BuildConfig.DEBUG) LinkLogLevel.VERBOSE else LinkLogLevel.ERROR } ``` ```java LinkLogLevel logLevel = BuildConfig.DEBUG ? LinkLogLevel.VERBOSE : LinkLogLevel.ERROR; LinkTokenConfiguration linkTokenConfiguration = new LinkTokenConfiguration.Builder() .token("LINK_TOKEN_FROM_SERVER") .logLevel(logLevel) .build(); ``` #### Troubleshooting OAuth errors  A troubleshooting guide for common OAuth errors is below. #### No redirect out of app  ##### Link user experience  * In Link, after clicking "Continue" on the OAuth screen, nothing happens. ##### Common causes  * The user may be using an unsupported browser that is not compatible with Plaid's OAuth redirects, such as DuckDuckGo. For more details on which browsers are supported, see [Supported browsers](https://plaid.com/docs/link/web/index.html.md#supported-browsers) . ##### Troubleshooting steps  #### No redirect back to app  ##### Link user experience  * After completing OAuth in the browser or financial institution's app, the user is not redirected back to your app. ##### Common causes  * The webpage is unable to locate an app on the device with a package id matching the one used to create the Link token. ##### Troubleshooting steps  #### The Play Store opened upon redirect  ##### Link user experience  * After completing OAuth in the browser or financial institution's app, the Google Play store opened. ##### Common causes  * The webpage is unable to locate an app on the device with the package id matching the one used to create the Link token. ##### Troubleshooting steps  #### Link opens, then immediately closes upon redirect  ##### Link user experience  After completing OAuth in the browser or financial institution's app, Link opens and then closes again. ##### Common causes  * The webpage redirected back to the wrong application on the device causing Link to open and immediately close again as it gets data from a different session. * You may have both a test and a release version of your app installed on your device and used the wrong package name when creating the Link token. ##### Troubleshooting steps  #### Other common errors  To troubleshoot an error with an error code, use the [error troubleshooting guide](https://plaid.com/docs/errors/index.html.md) . --- # Link - Optimizing Link conversion | Plaid Docs Optimizing Link conversion  =========================== #### Discover best practices for improving Link conversion  #### Overview  This guide contains tips for optimizing your existing Link implementation to help increase conversion and improve your users' experiences with Link. If you don't yet have a working Link integration, see the Link page for your desired SDK for instructions on getting started with Link. If you are using pay-by-bank flows, also see [Increasing pay-by-bank adoption](https://plaid.com/docs/auth/pay-by-bank-ux/index.html.md) for tips on getting users to use the Link-based payments flow rather than paying via card. #### Measuring Link conversion  Before making changes to your integration to improve conversion, it can be useful to understand your current conversion rates. To learn how, see [Tracking Link conversion](https://plaid.com/docs/link/measuring-conversion/index.html.md) . #### Improving Link conversion  Many different steps can be taken to maximize Link conversion, and the exact impact of these steps will vary for each customer and use case. The recommendations below are provided in general priority order. ##### Initialize with a minimal set of products  In general, calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with a minimal set of products will both increase conversion and reduce your costs. For more details, see [Choosing how to initialize products](https://plaid.com/docs/link/initializing-products/index.html.md) . ##### Implement full OAuth support on mobile, including app-to-app  While supporting mobile app-to-app impacts only a small number of banks (currently only Chase), the impact on conversion for eligible users is very large, as app-to-app flows can allow users to authenticate with biometrics instead of a username and password. For iOS, supporting app-to-app requires [creating an apple-app-site-association file](https://plaid.com/docs/link/oauth/index.html.md#ios-sdk-react-native-ios) to support universal links. On Android, supporting app-to-app requires [registering your Android package name](https://plaid.com/docs/link/oauth/index.html.md#android-sdk-react-native-android) . For more details, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md) . ##### Pre-initialize Link for lower UI latency  All Plaid SDKs offer a method to pre-initialize Link before opening it -- for example, by calling the `create()` method on web, React Native, or iOS, or creating a `PlaidHandler` on Android. It is recommended to call this method as soon as you load the view or screen from which the end user can open Link. Pre-initializing Link as soon as possible, before the `open()` method is called, results in lower latency for your end-user in loading the Link UI, leading to increased conversion. Support for pre-initialization was added in March 2024. You must be using an up-to-date version of Plaid Link SDKs to benefit from the performance enhancements of this approach. ##### Provide pre-Link messaging  Link conversion is highest when users have the right expectations set going into Link. Your app should explain why you use Plaid, the benefits for the user of connecting their account, and that the user's information will be secure. It should also set the user's expectations around what information they will need to provide during the Link flow. Plaid should be configured as the default experience. For more details, including visual examples, see [Pre-Link messaging for optimizing conversion](https://plaid.com/docs/link/messaging/index.html.md) . ##### Update the Link SDK regularly  Plaid makes continual updates to Plaid Link to improve conversion. If you are using Link on web, you will automatically be on the latest version; if you are using one of Plaid's SDKs for [iOS](https://github.com/plaid/plaid-link-ios) , [Android](https://github.com/plaid/plaid-link-android) , or [React Native](https://github.com/plaid/react-native-plaid-link-sdk) , we recommend you update regularly (ideally once a month, and at least once per quarter) to ensure you have access to the latest Link conversion improvements. ##### Provide a phone number during Link token creation  If you have the user's phone number, provide it in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request in the `user.phone_number` field. Plaid will pre-fill the phone number in Link for the user, allowing them to access the Returning User Experience without any data entry. For more details, see [Returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) . ##### (For Auth customers) Implement alternative Auth flows  While the vast majority of users can use Plaid's default Auth flows, some users, especially those at smaller banks and credit unions, have accounts that do not support those flows. Implementing micro-deposit-based or Database Auth flows will increase conversion by allowing these users to link their accounts. For more details, see [Auth coverage](https://plaid.com/docs/auth/coverage/index.html.md) . ##### (To increase Plaid uptake) Implement Embedded Institution Search  Implementing the [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) UI for Link has been shown to increase the percentage of customers who choose Plaid over an alternative flow. ##### Use Link Recovery  [Link Recovery (beta)](https://plaid.com/docs/link/link-recovery/index.html.md) allows you to recapture end users who abandoned Link due to temporary institution outages and notify them when the issue is resolved. To learn more and request access to the beta, see [Link Recovery](https://plaid.com/docs/link/link-recovery/index.html.md) . ##### Configure Link for your user's country and language  For apps with multi-language experiences, [custom profiles](https://plaid.com/docs/link/customization/index.html.md) improve conversion by allowing you to display Link in your user's preferred language. Calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with the `country` parameter set to your user's specific country, rather than all countries your app supports, will allow Link to show a more accurately targeted list of institutions. For Auth customers, calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with `country` set to just `US` is also required to enable the conversion-maximizing Instant Match and micro-deposit based [Auth flows](https://plaid.com/docs/auth/coverage/index.html.md) . ##### Customize Link with your organization's branding  Plaid allows you to customize certain aspects of the Link UI. Customizing these in a way that matches your app -- for example, [uploading your organization's logo](https://plaid.com/docs/link/customization/index.html.md#consent-pane-customizations) to be used on the Link consent pane or [matching your brand colors](https://plaid.com/docs/link/customization/index.html.md#color-scheme) can increase conversion. For more details, see [Customizing Link](https://plaid.com/docs/link/index.html.md) . ##### (If applicable) Use the Institution Select shortcut  If you already know the institution your user plans to connect before the Link flow is launched, you can highlight this institution in the Institution Select UI by specifying the [routing number](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-institution-data-routing-number) during the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. For more details, see [Institution Select shortcut](https://plaid.com/docs/link/customization/index.html.md#institution-select-shortcut) . --- # Link - Customizing Link | Plaid Docs Link customization  =================== #### Learn how to customize the Link UI for your app  #### Link customization overview  You have the ability to customize multiple parts of the Link UI from the [Plaid Dashboard](https://dashboard.plaid.com/link) . (An image of "Plaid dashboard showing Link customization options with institution selection, search bar, and list of bank logos.") You can create multiple Link customizations in order to show different versions of Link to different users. For example, you can show an English-configured customization to users who have set their language to English, and a French-configured customization to users who have set their language to French. Link customizations can also be used to create different segments for the purposes of tracking conversion rates and other analytics differences between different Link configurations. You can track this yourself, or, for customers with Premium Support Packages, Plaid can show the performance of different configurations in the Dashboard. For more details, see [Link analytics](https://plaid.com/docs/link/measuring-conversion/index.html.md) . To create a customization, access the **Link** menu within the [Plaid Dashboard](https://dashboard.plaid.com/link) and select **Link Customization**. You can then create a new customization by clicking on the drop-down menu in the upper right and selecting **Create new customization**. Or, to create a customization based on an existing customization, open the settings pane, accessible via the gear icon in the upper-right corner of the Link customization page, and use the **Duplicate** button. From the settings pane, you can also modify the countries and languages the customization applies to, as well as change its name. (An image of "Edit French settings pane showing options for countries, language, and customization name, with Duplicate, Save, and Delete buttons.") To use a customization, set the `link_customization_name` parameter to the customization name when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . In order for a customization to be applied, the language and country settings in Link must _exactly_ match those specified in the customization. For example, a customization with the country set to **United States** and **Canada** will not be applied if the `country_codes` setting provided to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) is `['US']`; it must be `['US', 'CA']`. #### Account Select  The Account Select pane is a required pane where users indicate which accounts they want to share data for. (An image of "Three Account Select panes in Plaid Link: one account selected, multiple accounts selected, and all accounts selected.") Enabled for one account, Enabled for multiple accounts, and Enabled for all accounts Account Select panes, respectively This pane can be configured to allow for single account selection, multi account selection, or all accounts preselected. Your use case may influence the setting you want to choose: * If your Plaid use case is banking, consumer payments, or wealth, we recommend that you use the "Enabled for one account" or the "Enabled for multiple accounts" view behavior. * If your Plaid use case is personal financial management or lending, you may prefer to use the "Enabled for all accounts" view behavior. When a user connects their account via a financial institution's OAuth flow, the Account Select pane may be skipped if Plaid determines that the flow has already fulfilled the account selection step (e.g. if Link is customized to enable multiple accounts to be selected and the financial institution's OAuth flow supports this step, Plaid's Account Select pane will not be shown). Note that if you have enabled multi account selection or all accounts selected, this behavior may be overridden in Link during Link flows that do not support the usage of multiple accounts. For example, the [Instant Match](https://plaid.com/docs/auth/coverage/instant/index.html.md#instant-match) and [Automated Micro-deposits](https://plaid.com/docs/auth/coverage/automated/index.html.md) Auth flows require the user to enter the account and routing number for a specific account, and can only be used with one account at a time. In these cases, Link will present a single account selection flow, regardless of your customization settings. After a user selects their accounts and clicks **Continue**, the Connected pane will be shown. The selected accounts will be specified in the [accounts](https://plaid.com/docs/link/web/index.html.md#link-web-onsuccess-metadata-accounts) property of the `onSuccess()` callback. ```javascript const onSuccess = useCallback( (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => { // updated selected account ids const account_ids = metadata.accounts.map(account => account.id); // ... }, [], ); ``` Only the data for the selected accounts will be available for the accounts via the API. You can listen for [NEW\_ACCOUNTS\_AVAILABLE](https://plaid.com/docs/api/items/index.html.md#new_accounts_available) webhooks to discover new accounts for the created Item and use [update mode with Account Select enabled](https://plaid.com/docs/link/update-mode/index.html.md#using-update-mode-to-request-new-accounts) to request data to be shared for new accounts from your users. For some older Items created before March 2023, data for all accounts may be available, even if the user did not select the account in Account Select, and access to new accounts may be granted without needing to use the update mode flow. If these Items are at OAuth institutions, they will be updated to use the current Account Select behavior when they are sent through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . #### Language and country  You can select the language Link will appear in, as well as the countries it should support, on the settings pane, accessible via the gear icon in the upper-right corner. The list of countries selected will control which institutions are displayed in Link, as well as whether the OAuth pane will appear. The language setting will determine the default strings used in the Link UI. If you want to customize the translation, you can edit the strings, as described in the [Text strings](https://plaid.com/docs/link/customization/index.html.md#text-strings) section below. Language and country are also specified via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , using the [country\_codes](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-country-codes) and `language` parameters. It is important that the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) parameters and customization settings match each other. If the language specified via `language` does not match the language selected for the customization, the customization will not be applied. If the country codes specified via [country\_codes](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-country-codes) do not match the country codes selected for the customization, the country codes selected for the customization may be overridden. Plaid supports over a dozen languages and countries in Link and is continually adding more. For an up-to-date list of supported languages and countries, see the [Dashboard](https://dashboard.plaid.com/link) or the [API Reference](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-language) . For Identity Verification, the language Link appears in is instead automatically selected based on the end user's browser settings. For more details, see [Identity Verification supported languages](https://plaid.com/docs/identity-verification/index.html.md#supported-languages) . #### Color scheme  You can configure the color scheme used by Link to match your company's brand colors or website color scheme via the **Background Color** setting. #### Text strings  You can change the text shown on some of the screens to customize the wording to your app. This setting can be configured via the **Consent**, **Institution Select**, **Institution Search**, **Connected** and **Re-Connected** settings. #### Financial institutions  Plaid recommends a default list of financial institutions whose logos are shown on the bank selection screen. This list is personalized based on user data, such as location. This option is automatically enabled; the **Automatic** option is pre-selected in the **Institution Select** setting. Alternatively, you can customize the list of institutions by choosing the **Custom** option, but this option may result in lower conversion. #### (Document Income only) Document upload settings  If you are using the [Document Income](https://plaid.com/docs/income/index.html.md) product, you can use Link customizations to individually enable or disable the different types of documents your customers are allowed to upload in Link. You can configure the following options: * What type of document can be uploaded * What filetypes of document can be uploaded * The minimum and maximum number of documents that can be uploaded Note that you must have Production access to Document Income before you can configure this setting; it will not appear if your Production access request has not yet been submitted or approved. Also note that bank statements are only supported with a custom contract. If you are not contracted for bank statements, do not enable bank statement uploads in your Link customization, as it will cause your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) calls to fail. To request access to bank statement uploads, contact sales or your account manager. #### Data Transparency Messaging  As of October 31, 2024, all new customers launching in the US and/or Canada must select a use case under the Data Transparency Messaging section of the Link customization UI in order to use Link in Production. Under the **Data Transparency Messaging** section of the Link customization, you can opt in to Data Transparency Messaging and/or select the use cases that will be displayed in Link during the Data Transparency Messaging flow. For more details, see [Data Transparency Messaging Migration Guide](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . #### Consent pane customizations  ##### Overview  The Consent pane is what users see when first entering Plaid Link and where they consent to the [end-user privacy policy](https://plaid.com/legal/#end-user-privacy-policy) . Plaid offers the option to select whether Plaid branding or a combination of your branding and Plaid's is featured. This latter option includes the ability to upload a brand color as well as a brand logo. (An image of "Two consent panes: one with Plaid logo, the other co-branded with WonderWallet. Both outline secure account connection and privacy.") Co-branded Consent pane and Plaid-branded Consent pane respectively Headlines are standardized based on which products Link is initialized with. ##### Product-mapped titles  | Product(s) | Title text | | --- | --- | | `assets`, `auth`, `identity`, `investments`, `liabilities`, `transactions` | \[App name\] uses Plaid to connect your \[custom field\] | | `employment` (beta) | \[App name\] uses Plaid to verify your employment | | `income_verification` | \[App name\] uses Plaid to verify your income | This version of the Consent pane is only available to Link customization settings targeting the US and Canada. ##### Customizing the Consent pane  Within the [Link Customization page](https://dashboard.plaid.com/link) , under the **Consent** section, you can choose to activate the Plaid-branded Consent pane or the co-branded Consent pane. If you choose the co-branded experience, you will see a box that will guide you to choosing your logo, and if you wish, a brand color that will be used for the animation on the loading screen. You **must** upload a logo (1024 x 1024 .png file) to use the co-branded experience. You can upload a logo or brand color directly within the Consent experience, or you can make the same changes within the Team Settings page. You can also choose to enable [Data Transparency Messaging (beta)](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) where you can describe your use case for accessing the data types that you are requesting. Note that enabling Data Transparency Messaging on the Consent Pane will prevent your access to products beyond those that you pass to Link. For more information, see [Enabling Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) . Once you are done configuring your new Consent pane, click **Publish** and your new changes will go into effect. #### Other customizable settings  Several other settings exist to configure Link, outside of the customization pane. ##### Account subtype filters  Account filters allow you to select which account types and subtypes will be available in Link. For example, if you only want users to link a checking account, you can use Link to display only Items that contain checking accounts. This setting will apply to both the Account Select view and the Institution Select view. Account filters can be configured via the [account\_filters](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-account-filters) parameter when creating a Link token. For details, see [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . Account types and subtypes that are not compatible with the products used to initialize Link will be automatically omitted and do not require an account filter setting. For details on account type and subtype compatibility, see the [Account type / product support matrix](https://plaid.com/docs/api/accounts/index.html.md#account-type--product-support-matrix) . For information on using account subtype filters to opt in to showing rent-tech institutions in Link, see [Enabling limited purpose checking accounts for rent or mortgage](https://plaid.com/docs/auth/index.html.md#enabling-limited-purpose-checking-accounts-for-rent-or-mortgage) . ##### Institution Select shortcut  The Institution Select shortcut can be enabled to create a streamlined Link experience for users when you already know which institution the user wants to connect to before initializing Link. For example, this could be the case when migrating to Plaid from an ACH implementation where users manually entered their account and routing number. You can pass `routing_number` into the `institution_data` request field in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. The matched institution will be listed first in the default list of institutions shown for that session. If the end user chooses the matched institution, Plaid will send the `MATCHED_SELECT_INSTITUTION` event callback with metadata `{match_reason: routing_number}`. --- # Link - Data Transparency Messaging migration | Plaid Docs Data Transparency Messaging Guide  ================================== #### How to enable and manage Data Transparency Messaging for your application  As of October 31, 2024, all new Plaid Inc. customers launching to end users in the US and/or Canada are automatically enrolled for Data Transparency Messaging and must [select a use case](https://dashboard.plaid.com/link/data-transparency-v5) to use Link in Production. This does not apply customers who use only products that don't connect to financial institutions, like Identity Verification, or to customers using only Consumer Report or other Plaid Check products. #### Introduction  Plaid has introduced Data Transparency Messaging (DTM) into the Link flow to help you stay in compliance with the [1033 rule](https://plaid.com/resources/compliance/section-1033/) . This experience provides end users (consumers) with a greater understanding of the types of data that they share with you and Plaid. When using DTM, a user is informed of the specific data types that you are requesting and the reason that you are requesting them (use cases). If you want access to additional data from a user after their initial Link, or to use the data for additional use cases, they must consent to sharing that data through a separate consent flow. This guide covers the implementation changes required to implement the Data Transparency Messaging feature. (An image of "Plaid's Data Transparency Messaging: Log in at Gingham Bank, disclose account info, select accounts, with product-specific disclosures.") DTM introduces product-specific disclosures above the "Continue" buttons on key screens such as the OAuth handoff pane and "Account Select" pane (pictured). If the user clicks the Learn More link within the disclosure, the "Why is this needed" half-pane appears. ##### Who is affected  Data Transparency Messaging (DTM) will be required for all Plaid customers, unless you meet one of the criteria below: * You use only products that don't connect to financial institutions: Identity Verification, Beacon, Monitor, or Enrich. * You serve end users only in Europe. If you serve end users in Canada but not the United States and would like to opt out of Data Transparency Messaging, contact your account manager. * You use only Plaid Check products (i.e. Consumer Report) rather than Plaid Inc. products. ##### What's new  * The API will only return data for products that users have consented to through Link. In addition to the existing `products` field, we have added a new configuration field called `additional_consented_products` that can be used to gather consent for additional products. * Link can be configured to display DTM. The language will appear as a footer on the OAuth pane (shown to consumers before they are directed to an institution's OAuth flow), or the Account Select pane for sessions that do not go through OAuth. * If enabled via the Plaid Dashboard, DTM must be configured to include at least one use case, which explains to users the purpose of the data being requested. You may choose up to 3 use cases for each Link customization that will be shown in Link to your users. You can select these use cases via the [Dashboard Link Customization page](https://dashboard.plaid.com/link/data-transparency-v5) . * Products that require data not consented to by users through Link cannot be accessed without going through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . Data Transparency Messaging is available to all customers who are enabled for US or Canada on an opt-in basis. New customers will be automatically enabled for Data Transparency Messaging, and some existing customers have been automatically enabled for Data Transparency Messaging. For existing customers who have not yet been enabled for Data Transparency Messaging, Plaid will provide more details on the enablement timeline once it has been finalized. #### Migration overview  1. Review your API integration and, if necessary, [populate the additional\_consented\_products field](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md#additional-consented-products) with products you want to gather consent for. Every product that you currently use should be included in either the `products`, `optional_products`, `required_if_supported_products` or `additional_consented_products` fields. For more information on the differences between these fields, see [Initializing products](https://plaid.com/docs/link/initializing-products/index.html.md#overview) . 2. Update the use cases for each Link customization via the [Dashboard](https://plaid.com/docs/link/customization/index.html.md) . 3. (Optional) [Update Link customizations](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md#updating-link-customizations) to enable DTM via the [Dashboard](https://plaid.com/docs/link/customization/index.html.md) . 4. (Future) Configure [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to renew consent. #### Additional consented products  Previously, as long as you were approved and enabled for a product during your Plaid Dashboard Production Request process, you could request and start using it by calling the corresponding product API route on any Item. Going forward, any Item that goes through Link with DTM enabled restricts your access to new product data unless the Item has the required consent; if you do not have the required consent, you will receive the error [ADDITIONAL\_CONSENT\_REQUIRED](https://plaid.com/docs/errors/invalid-input/index.html.md#additional_consent_required) . Additional consent will need to be collected through update mode. If you need to use a product but don't want Plaid to try to extract that data immediately, you can create a Link token with [additional\_consented\_products](https://plaid.com/docs/api/link/index.html.md#link-token-create-request-additional-consented-products) specified. These products will be shown in Link as part of DTM, but will not be fetched or billed until you request them. Specifying `additional_consented_products` will not have any impact on Items created before DTM is enabled, but it is recommended that you start using this field so you can be ready when DTM is enabled for your Link flows. The products in the `additional_consented_products` field may not have any overlap with products listed in the `products`, `optional_products` or `required_if_supported_products`. The `products` array must contain at least one product. In the DTM language, Link will show data scopes corresponding to the union of `products`, `optional_products`, `required_if_supported_products`, and `additional_consented_products`. Products placed in the `additional_consented_products` field do not have any impact on institution filtering or account subtype filtering. For example, if `auth` is an `additional_consented_product`, users will be allowed to select any account, not just checking/savings accounts. When your existing Items are migrated to DTM, Items in the US or Canada created without DTM will have the following migration applied: the `billed_products`, along with any additional products that use the same data scopes, will be automatically added to the `consented_products` field for those Items. You will be notified when your Items are scheduled to be migrated. #### Updating Link customizations  To opt into DTM, go to your [Link customization](https://dashboard.plaid.com/link/privacy-interstitial) or create a new one (you may duplicate an existing customization by using the [duplicate feature](https://plaid.com/docs/link/customization/index.html.md#link-customization-overview) ), click on the Data Transparency section, where you can customize the use case. You must have at least one selected use case to save the customization. You can preview the primary footer language and the detailed panel. This language will appear on the OAuth pane for sessions that go through OAuth, and on Account Select otherwise. Use cases will only be shown in Link if the end user clicks the "Learn more" link within the DTM disclosure text. | Category | Use cases | | --- | --- | | Payments | Send and receive money, Pay your bills, Make a purchase online, Facilitate business-to-business payments, Fund your account | | Identity verification and fraud | Verify your identity and prevent fraud, Verify your account, Protect against fraud | | Personal / Business finance management | Track and manage your finances, Prepare your taxes, Get rewards, Invest your money, Do business accounting and tax preparation, Prepare and categorize invoices, Manage employee expense reporting, Track, manage and build your credit, Access your paycheck sooner, Pay down debt | | Credit underwriting | Get considered for a loan, Verify your income | There is no restriction enforced on which use case(s) you select beyond the limit of three use cases per customization. For example, you may still select a payments-related use case even if you are not Production-enabled for any payments-related products and not initializing Link with any payments-related products. In the Production environment, the use cases you select will also visible to consumers via the Plaid Portal ([my.plaid.com](https://my.plaid.com/) ) and to Plaid financial institution partners. Once you've selected how you want to present DTM to users and selected at least one use case, click Publish. Your changes will go into effect the next time you initialize Link with this customization. Only newly created Items created with the updated customization will have the new API behavior; existing Items will not be affected. If you want to prepare for the DTM automatic enablement date without enabling DTM earlier than necessary, you can add use cases to your [Link customization](https://dashboard.plaid.com/link/privacy-interstitial) without enabling DTM. If you currently use additional products after Link that you do not initialize via the `products` field, it is recommended that you update your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) code to include `additional_consented_products` before enabling this feature in the Plaid Dashboard to avoid losing access to the additional API endpoints on your new Items. #### Authorization records  You may need to review authorization records to meet audit requirements or to make decisions about collecting additional consent. Current authorization details such as an Item's consented products and consented use cases are available via the [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) endpoint. These are updated in near real time and may be used to configure update mode to request additional consent from a user. Historical authorization records are available via [/consent/events/get](https://plaid.com/docs/api/consent/index.html.md#consenteventsget) . These records will be retained and available for at least 3 years (though the earliest records will begin in November 2024). Authorization details and historical authorization records will only be available for Items that have been enabled for Data Transparency Messaging. #### API changes  For Items that have gone through Link with Data Transparency Messaging enabled, there will be new `consented_products` and `consented_data_scopes` fields returned by the [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) endpoint. You will see the error code [ADDITIONAL\_CONSENT\_REQUIRED](https://plaid.com/docs/errors/invalid-input/index.html.md#additional_consent_required) if you do not have consent to a product you are trying to request. This is the same error you would get if you are not enabled for the product. To resolve `ADDITIONAL_CONSENT_REQUIRED` errors, you will need to send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md#requesting-additional-consented-products) . #### Data scopes and consent  The products you request for Link Initialization are not mapped 1:1 with the different data scopes displayed. Our goal is to allow consumers to understand what types of data they are permissioning, and product names alone can be confusing to consumers. Because data scopes can be broad, in certain cases, you will get consent for more than just the products you initialize Link with. For example, the Assets product requires consent to both the "Transactions" and the "Account Holder Information" data scopes, so the Transactions and Identity products will both be consented to by default. To understand which products you have consent to access for a given Item, you can use the `consented_products` field on the [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) or product endpoints as detailed above. Note that the data scopes used by Plaid should not be confused with OAuth data scopes. Some institutions that use OAuth define their own data scopes, and users at OAuth institutions may be required to grant consent to both Plaid's data scopes and institution-specific OAuth data scopes during the Link flow. For more information on OAuth data scopes, see [Scoped consent](https://plaid.com/docs/link/oauth/index.html.md#scoped-consent) in the OAuth documentation. ##### Data scope descriptions 
Account and balance info
May include account details such as account name, type, description, balances, and masked account number.
Contact info
May include account owner name, email, phone, and address.
Account and routing number
Includes account number and financial institution routing numbers.
Transactions
May include transaction details such as amounts, dates, price, location, spending categories and descriptions, and insights like recurring transactions.
Credit and loans
May include details about your credit and loan accounts, such as balance, payment dates and amounts due, credit limit, repayment status, interest rate, loan terms, and originator info.
Bank Statements
May include account info such as activity and usage, and contact details.
Investments
May include info about investment accounts, such as securities details, quantity, price, and transactions.
Risk info
May use account info such as activity and usage, contact details, transaction-related information, and Plaid connection history to provide an assessment of fraud and/or minimize overdrafts
##### Data scopes by product  | Plaid Product | Data scopes required | | --- | --- | | Account Risk (beta) | Account and balance info, Contact info, Transactions, Risk info | | Assets | Account and balance info, Contact info, Transactions | | Auth: Instant Auth or Instant Match | Account and balance info, Contact info, Account and routing number | | Auth: Database Auth, Database Insights, or Database Match | Account and routing number | | Auth: Same-Day Micro-deposit or Instant Micro-deposit | Account and routing number | | Auth: Automatic Micro-deposit | Account and balance info, Contact info, Transactions, Account and routing number | | Balance | Account and balance info | | Bank Income | Account and balance info, Contact info, Transactions | | Consumer Report by Plaid Check | Account and balance info, Contact info, Transactions | | Statements | Account and balance info, Contact info, Statements | | Identity (includes Identity Match) | Account and balance info, Contact info | | Investments | Account and balance info, Contact info, Investments | | Liabilities | Account and balance info, Contact info, Credit and Loans | | Signal Transaction Scores | Account and balance info, Contact info, Transactions, Risk info | | Transactions (includes Recurring Transactions) | Account and balance info, Contact info, Transactions | | Transfer | Account and balance info, Contact info, Account and routing number | | Investments Move (fka Investments Auth) (beta) | Account and balance info, Contact info, Account and routing number, Investments | Account and balance info and Contact info are almost always requested; there are some exceptions for products like Database Match or Database Insights where Plaid does not pull data from the bank, and does not require this information. Plaid will disclose all the underlying data scopes needed to deliver the product. For example, Signal Transaction Scores uses Transactions data as one input to derive the score, so we disclose that the data scope Transactions was accessed, even if you do not request the product Transactions in `products` or `additional_consented_products`. In this case, Plaid will record the user's consent to the Transactions data scope. If you request a product requiring the Transactions data scope in the future, you will not need to use update mode. (But if you are adding a new use case as well, you will need to use update mode to request consent for that use case, even if you already have the required product consent.) Some Plaid products do not have any associated bank data scopes because they do not rely on access to bank data. For example, Identity Verification, Document Income, and Payroll Income do not rely on bank data. #### Requesting consent for additional products or use cases in update mode  If you would like to start collecting product data for an Item that you did not collect enough consent for during initial creation, you are able to send that Item through update mode to collect new consent. For details, see [Requesting additional consented products](https://plaid.com/docs/link/update-mode/index.html.md#requesting-additional-consented-products) and [Requesting additional use cases](https://plaid.com/docs/link/update-mode/index.html.md#requesting-additional-use-cases) in the update mode documentation. #### Automatic migration path  If you do not choose to follow any of the steps in this guide, your eligible Link sessions (those including a country code of `US` and/or `CA`) will be automatically enabled for Data Transparency Messaging. No date has been finalized for this automatic migration; Plaid will provide details when it has been determined. When your team is automatically enabled for Data Transparency Messaging, the following migrations will occur: * Plaid will enable DTM for your Items and Link flows. If you have not customized your use cases as described in [Updating Link customizations](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md#updating-link-customizations) , the use cases presented in the Link UI will be automatically populated based on information you have previously provided to us (e.g. in the Production Request Form). * If you do not specify `additional_consented_products` in your [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call, Plaid will perform an assessment of your historical product add behavior. If, in the last 6 months before the enforcement date, you had billable activity for a product, and that product is not included in the `products`, `required_if_supported_products`, or `optional_products` arrays, Plaid will automatically update your Link session to request consent for that product as though that product had been added to the `additional_consented_products` array. To opt out of this behavior, contact your account manager. DTM is mandatory for all customers who are enabled for Plaid in the US. While Canada-based Link sessions are not subject to 1033 enforcement, they will receive DTM to provide enhanced consumer transparency. If you are enabled for Canada but not for the US and want to opt out of automatic DTM enablement, contact your account manager. #### Minimum client library version for using additional consented products  * [Python](https://github.com/plaid/plaid-python/blob/master/CHANGELOG.md) \- 9.3.0 * [Node](https://github.com/plaid/plaid-node/blob/master/CHANGELOG.md) \- 10.4.0 * [Ruby](https://github.com/plaid/plaid-ruby/blob/master/CHANGELOG.md) \- 15.5.0 * [Java](https://github.com/plaid/plaid-java/blob/master/CHANGELOG.md) \- 11.3.0 * [Go](https://github.com/plaid/plaid-go/blob/master/CHANGELOG.md) \- 3.4.0 --- # Link - Preventing duplicate Items | Plaid Docs Preventing duplicate Items  =========================== #### Prevent unnecessary billing and confusing application behavior  [Watch video](https://www.youtube.com/watch?v=6wWPKrVPaio) #### How duplicate Items are created  An [Item](https://plaid.com/docs/quickstart/glossary/index.html.md#item) represents a login at a financial institution. This login typically happens when an end user links an account (or several accounts) using [Plaid Link](https://plaid.com/docs/link/index.html.md) . A duplicate Item will be created if the end user logs into the same institution using the same credentials again using Plaid Link (in the same application), and if an access token is requested for the Item. Duplicate Items can occur for multiple reasons. For example, a duplicate Item can occur if a user accidentally links the same account more than once, because they do not realize they already linked an account, or because their linked account is no longer working. Duplicate Items can also occur if a user intentionally links multiple Items for abusive purposes (for example, as part of an attempt to receive multiple sign-up bonuses or to evade a ban). Duplicate Items can create confusing or unwanted behavior in your application, can sometimes be a vector for fraud and abuse, and may cause you to be charged multiple times for the same Item. We recommend building safeguards in your application to help prevent end users from creating duplicate Items. In this article, we'll describe a few ways to prevent and detect Item duplication. #### Preventing duplicate Items  ##### Use the onSuccess callback metadata  The [onSuccess](https://plaid.com/docs/link/web/index.html.md#onsuccess) callback is called when a user successfully links an Item using Plaid Link. This callback provides metadata that you can use to prevent duplicate Items from being created. (Alternatively, if you're using a connection method that does not provide data in the `onSuccess` callback, such as Hosted Link, you can obtain this metadata by calling [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) and using the `results.item_add_results` array.) One approach is to require a user login prior to launching Plaid Link so that you can retrieve existing Items associated with the user. Then, before requesting an `access_token`, examine and compare the `onSuccess` callback metadata to the user's existing Items. You can compare a combination of the accounts' `institution_id`, account `name`, and account `mask` to determine whether an end user has previously linked an account to your application. Do not exchange a public token for an access token if you detect a duplicate Item. While the `mask` value is usually the same as the last 4 digits of the account number, this is not the case at all institutions. Never detect duplicate Items by attempting to match a `mask` with an account number. Sample onSuccess metadata schema ```javascript { institution: { name: 'Wells Fargo', institution_id: 'ins_4' }, accounts: [ { id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy', name: 'Plaid Checking', mask: '0000', type: 'depository', subtype: 'checking', verification_status: '' }, { id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4', name: 'Plaid Saving', mask: '1111', type: 'depository', subtype: 'savings' } ... ], link_session_id: '79e772be-547d-4c9c-8b76-4ac4ed4c441a' } ``` Note that duplicate Items are not always identical. For example, an Item may have a checking account linked, while its duplicate may have only a savings account linked. While this scenario is rare, if it becomes a problem for your use case, you can switch to using the `institution_id` field on a per-user basis to prevent duplicate Items and enforce that each user of your app not link multiple Items with the same institution. However, because this is a legitimate use case for some applications, it is not recommended as the primary means of detecting duplicate Items. Duplicate Items at Chase, PNC, NFCU, and Schwab For Chase, PNC, Navy Federal Credit Union, and Charles Schwab, existing Items may be invalidated if an end user adds a second Item using the same credentials, at the point when the user has completed the institution's OAuth flow. For the aforementioned providers other than Charles Schwab, this will only happen if the second Item does not have exactly the same set of accounts associated as the first Item (i.e. the user granted permissions to different accounts in the institution's OAuth flow). If this occurs, delete the old Item using [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) and use the new Item. Alternatively, the old Item can repaired using [update mode](https://plaid.com/docs/link/update-mode/index.html.md) , which will invalidate the new Item. Then you may delete the new Item. For Auth or Transfer customers, Chase or PNC Item invalidation caused by creating a duplicate Item will not invalidate or change the Item's TAN. ##### Implement Pre-Link messaging  A lightweight but effective method for preventing accidental duplicate Items from being created is by providing relevant messaging and information to end users before they engage with Plaid Link in your application. For example, displaying a list of accounts they've already connected to your application can help prevent end users from inadvertently linking the same accounts again. ##### Use Link's update mode  From time to time, an Item may become unhealthy due to entering the `ITEM_LOGIN_REQUIRED` state. Or, the Item may still be healthy, but you may want your end user to authorize additional accounts or permissions associated with the Item. When either of these scenarios happens, use [Link in update mode](https://plaid.com/docs/link/update-mode/index.html.md) to refresh the Item instead of creating a new Item. #### Example implementation: Preventing accidental duplicate Items  For an example that demonstrates how to prevent accidental duplicate Items, see the [Plaid Pattern](https://github.com/plaid/pattern) sample app. Plaid Pattern implements simple server-side logic to check whether the user ID and institution ID pair already exist in the application database. If the pair exists, an access token will not be requested for this Item, thereby preventing a duplicate. In addition, a message is displayed to the end user informing them that they've already linked this Item. The relevant code can be found in [/server/routes/items.js](https://github.com/plaid/pattern/blob/master/server/routes/items.js#L41-L49) and [/server/db/queries/items.js](https://github.com/plaid/pattern/blob/master/server/db/queries/items.js#L73-L88) . #### Identifying existing duplicate Items  To identify existing duplicate Items, use the same matching logic as described above, but retrieve this data via the [/accounts/get](https://plaid.com/docs/api/accounts/index.html.md#accountsget) endpoint instead of the `onSuccess` callback. Occasionally, the `mask` or `name` fields may be null, in which case you can compare `institution_id` and `client_user_id` as a fallback. After identifying duplicate Items, use the [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) endpoint to delete an Item. If you are using Auth via [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) , existing duplicate Items may be detected by using the account and routing number fields and looking for duplicates. This method will not work for Items at institutions that use [Tokenized Account Numbers (TANs)](https://plaid.com/docs/auth/index.html.md#tokenized-account-numbers) . To detect existing duplicate Items at these institutions, you can use the [persistent\_account\_id](https://plaid.com/docs/api/accounts/index.html.md#accounts-get-response-accounts-persistent-account-id) field, which will be the same across duplicate instances of the Item. #### Detecting and preventing duplicate Items across user accounts  When attempting to detect or prevent duplicate Items, your approach should depend on the type of duplicate Item you are trying to prevent. For example, you can often scope your search to either a single user's accounts, or to all accounts known to your application. If you are attempting to prevent accidental duplicate Items, you should scope the search to a single user; if you are attempting to detect or prevent abuse, it may make more sense to expand your search to all accounts that have been linked to your app. Note that there can be legitimate use cases for the same financial institution account to be linked across multiple different user accounts (for example, family members who share a joint bank account, or employees of the same company who share access to a business account); depending on your use case, you may want to incorporate this data into a broader abuse detection framework rather than blocking all duplicate accounts. --- # Link - Embedded Link | Plaid Docs Link Embedded Institution Search  ================================= #### Enhance uptake of Plaid by embedding institution search directly into your app  With Embedded Institution Search (also known as Embedded Link), you can provide a more seamless transition to the account connectivity experience and increase the percentage of users who choose Plaid. For payment experiences in particular, embedding institution search can help guide users to choosing their bank account as a payment method. [Watch video](https://www.youtube.com/watch?v=TqUo9z-r3x8) Embedded Institution Search and [Database Auth](https://plaid.com/docs/auth/coverage/database-auth/index.html.md) are both designed to increase adoption of ACH payment methods and are frequently used together. Embedded Institution Search is also fully compatible with other Auth flows, including micro-deposit based flows. #### Who should use Embedded Institution Search  Embedded Institution Search is recommended when: * You want to encourage your user to use Plaid, either because Plaid is your only flow, or because you benefit when the user chooses Plaid over an alternative (e.g. pay-by-bank flows). * Your design can accommodate a Plaid embed of at least **350x300px or 300x350px**. * You are not using Multi-Item Link. * You are not using one of Plaid's legacy credit products such as Assets, Statements, or the older (non-Plaid-Check-based) Income product. Embedded Institution Search can be used with the following products: Auth, Identity, Balance, Signal, Transfer, Transactions, Investments, Assets, Liabilities, and all Plaid Check Consumer Report products. Embedded Institution Search is not compatible with [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) . ##### Embedded Institution Search for pay-by-bank flows  It is highly recommended to use Embedded Institution Search for Link to increase uptake of pay-by-bank if your use case involves a pay-by-bank payments flow where the end user can choose between paying via a credit card and paying via a bank account. If your use case is an account opening or funding flow that requires the customer to use a bank account, or has a surcharge for credit card use, use the standard Link experience instead. In order to realize the benefits of Embedded Institution Search, you must show it by default when the payments view loads, without requiring the user to first select 'Pay by bank'. If you cannot do this, use the standard Link experience instead. For recommendations on how to improve the uptake of pay-by-bank and optimize your Embedded Institution Search UX, see [Increasing Pay-by-bank adoption](https://plaid.com/docs/auth/pay-by-bank-ux/index.html.md) . #### Institution Search user experience  The user will be able to select from a set of institution logos. This set of logos is customized based on user data, such as location. Alternatively, you can choose which logos will be displayed via the Plaid Dashboard. If a user selects an institution, they will be taken to Link to connect their account. (An image of "Payment options screen with monthly plan selected, pay by bank method, search bar, and bank logos. Pay button at the bottom.") Example of Embedded Institution Search on Desktop (An image of "Mobile flow showing institution search, log in to Gingham Bank, and success confirmation via Plaid for payment setup.") Example of Embedded Institution Search flow on mobile when user selects an institution If the user's institution is not one of the featured institutions, they can search for their institution using the search bar. (An image of "Search for a bank in the checkout payment method section using the search bar or select from listed institutions; option to connect manually.") Example of searching for an institution in Embedded Institution Search on desktop #### Returning user experience  The Embedded Institution Search experience can be further optimized for users who have already connected a financial account with Plaid. (An image of "Returning user form in Embedded Institution Search with fields for name, address, city, state, and zip code, and a 'Continue' button.") Example of the returning user experience in Embedded Institution Search When a user's device is recognized or the phone number is provided via [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , Plaid will check to see if they are a returning user. If they are detected as a returning user, Link will run a security check on the session in the background. If this check passes, the user will be shown a list of previously connected accounts in the embedded module. The user can then verify their phone number using a one-time password and complete the account linking process if the previously linked institutions do not require re-authentication. For more details on the returning user flow, see [Returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) . Note that if Plaid Check Consumer Report products are included in the Link token request, then returning users will see the default Institution Search user experience. ##### Testing in Sandbox  In order to test the returning user experience in Embedded Institution Search, use the phone numbers listed in [Testing returning user experience in Sandbox](https://plaid.com/docs/link/returning-user/index.html.md#testing-in-sandbox) . #### Integration steps  Embedded Institution Search is available for all supported integration modes except webviews and Hosted Link. Embedded Institution Search cannot be rendered inside an iFrame. Before integrating, make sure you are using a version of the SDK that supports Embedded Institution Search. | Platform | Minimum SDK version required | | --- | --- | | [Android](https://github.com/plaid/plaid-link-android) | 3.14.0 | | [iOS](https://github.com/plaid/plaid-link-ios) | 4.5.0 | | [React Native](https://github.com/plaid/react-native-plaid-link-sdk) | 10.6.0 | | [React web](https://github.com/plaid/react-plaid-link) | 3.5.1 | | JavaScript web | N/A (all customers are on the latest version) | 1. Create a Link token as normal, using [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) ; no special parameters are required when making this call to enable Embedded Institution Search. The 'Connect Manually' button rendering is configured with the `auth_type_select_enabled` boolean in the `auth` object. 2. Create an embedded view. This should be done before it will be displayed in your app, to minimize latency. Plaid will track when this view is requested and activate the Embedded Search UI. If you are using iOS, call `createEmbeddedView`, which will return a Result containing a `UIView`. Once you have the `UIView`, add it to your `ViewController`'s view. If you are using the web SDK, call `Plaid.createEmbedded` instead of `Plaid.create` to open Link. For other platforms, you will create the view as normal. 3. Lay out the view Plaid returns from the configuration. Using a **minimum size of 350x300px or 300x350px** is strongly recommended. Smaller sizes will significantly degrade conversion. If you are migrating to Embedded Institution Search from traditional Link, delete your old Link presentation in favor of this new one. Select group for content switcher iOSAndroidJavaScriptReact Embedded Institution Search - iOS (Swift) ```swift private func setupEmbeddedSearchView(token: String) { // Create a configuration like normal. var configuration = LinkTokenConfiguration( token: token, onSuccess: { success in print("success: \(success)") } ) configuration.onEvent = { event in print("Event: \(event)") } configuration.onExit = { exit in print("Exit: \(exit)") } // Create a handler with your configuration like normal. let handlerResult = Plaid.create(configuration) switch handlerResult { case .success(let handler): // Save a reference to your handler. self.handler = handler // Create an embedded view. let embeddedSearchView = handler.createEmbeddedView(presentUsing: .viewController(self)) // Layout this view embeddedSearchView.translatesAutoresizingMaskIntoConstraints = false view.addSubview(embeddedSearchView) NSLayoutConstraint.activate([ embeddedSearchView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 8), embeddedSearchView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 25), embeddedSearchView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -25), embeddedSearchView.heightAnchor.constraint(equalToConstant: 360), ]) case .failure(let error): // Error creating handler. Handle like normal. fatalError("\(error)") } } ``` Embedded Institution Search - Android (Kotlin) ```kotlin // Register a callback for an Activity Result like normal (must be done from an Activity) private val linkAccountToPlaid = registerForActivityResult(OpenPlaidLink()) { result -> when (result) { is LinkSuccess -> /* handle LinkSuccess */ is LinkExit -> /* handle LinkExit (from LinkActivity) */ } } // Create a linkTokenConfiguration like normal val linkTokenConfiguration = LinkTokenConfiguration.Builder().token(token).build() // Create the view with a trailing lambda for handling LinkExits from the Embedded View val embeddedView = Plaid.createLinkEmbeddedView( this /*Activity context*/, linkTokenConfiguration, linkAccountToPlaid) { exit: LinkExit -> /* handle LinkExit (from Embedded View) */ } // Add this embeddedView to a view in your layout binding.embeddedViewContainer.addView(embeddedView) ``` Embedded Institution search - web (HTML) ```html ``` Embedded Institution Search - web (JavaScript) ```javascript // The container at `#plaid-embedded-link-container` will need to be sized in order to // control the size of the embedded Plaid module const embeddedLinkOpenTarget = document.querySelector('#plaid-embedded-link-container'); Plaid.createEmbedded( { token: 'GENERATED_LINK_TOKEN', onSuccess: (public_token, metadata) => {}, onLoad: () => {}, onExit: (err, metadata) => {}, onEvent: (eventName, metadata) => {}, }, embeddedLinkOpenTarget, ); ``` Embedded Institution Search - web (React) ```javascript import React, { useCallback } from 'react'; import { PlaidEmbeddedLink } from 'react-plaid-link'; const App = props => { const onSuccess = useCallback( (token, metadata) => console.log('onSuccess', token, metadata), [] ); const onEvent = useCallback( (eventName, metadata) => console.log('onEvent', eventName, metadata), [] ); const onExit = useCallback( (err, metadata) => console.log('onExit', err, metadata), [] ); const config = { token: "plaid-token-123", onSuccess, onEvent, onExit, }; return ( ); }; export default App; ``` For an end-to-end example app, see the [Transfer Quickstart](https://github.com/plaid/transfer-quickstart/) , which incorporates Embedded Institution Search in a JavaScript frontend. ##### Update mode  Embedded Institution Search cannot be used in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) ; to update a user's Item, launch a regular update mode session instead. #### Customization Options  You can customize the Embedded Institution Search user experience to match your application's needs. ##### Module responsiveness and tile count  The embedded Link module will responsively scale to display between two and fifteen institutions, depending on the height and width of the module. Using a **minimum size of 350x300px or 300x350px** is strongly recommended, as smaller sizes degrade conversion particularly on returning user flows. Testing both embedded search and returning user experiences at your chosen module size to ensure usability is also strongly recommended. On the web, the embedded Plaid module will attempt to use 100% of the height and width of its container. To modify the size of the Plaid module, or to render the Plaid module responsively, you should set the size of the container. Plaid recommends using the largest container that will comfortably fit in your UI. The larger the container, the more institution logos will be shown. Users are more likely to adopt pay-by-bank when they see their institution's logo on the embedded Link screen. ##### Customizing institutions displayed  The institutions displayed in Link Embedded Search are based on your [Institution Select settings](https://dashboard.plaid.com/link/institution-select) , which you can optionally customize in the [Dashboard](https://dashboard.plaid.com/link/institution-select) . For most customers, it is recommended to use the default settings. Embedded Institution Search is compatible with the [Institution Select Shortcut](https://plaid.com/docs/link/customization/index.html.md#institution-select-shortcut) : If you already know which institution the user wants to connect to before initializing Link, you can pass `routing_number` into the `institution_data` request field in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. The matched institution will be listed first (top left position) in the embedded institution grid. #### Event callbacks emitted by Embedded Institution Search  ###### User chooses an institution directly from embedded search  * `onEvent: OPEN` – `view_name: "CONSENT"` * `onEvent: SELECT_INSTITUTION` * `onEvent: TRANSITION_VIEW` – `view_name: "CONSENT"` * `onEvent: TRANSITION_VIEW` – `view_name: "CREDENTIAL" or "OAUTH"` - user selects Continue on the ConsentPane Note that viewing the Embedded Institution Search pane will not result in any Link events or analytics activity. Only when the end user interacts with Embedded Institution Search will events appear. #### UI Recommendations for Embedded Institution Search  See [Increasing pay-by-bank adoption](https://plaid.com/docs/auth/pay-by-bank-ux/index.html.md) for recommendations on displaying Embedded Institution Search within your app for pay-by-bank use cases. --- # Link - Handling an invalid Link Token | Plaid Docs Handling an invalid Link Token  =============================== #### Catch the error in the onExit callback and refetch a new link\_token for the next time the user opens Link  Occasionally, the end user may invalidate the existing `link_token` that was used to open Link by taking too long to go through the flow (30+ minutes), or attempting too many invalid logins. If this happens, Link will exit with an [INVALID\_LINK\_TOKEN](https://plaid.com/docs/errors/invalid-input/index.html.md#invalid_link_token) error code. To allow your user to open Link again, recognize the error in the `onExit` callback, fetch a new `link_token`, and use it to reinitialize Link. You can obtain a new `link_token` by making another [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request: ```node app.post('/api/create_link_token', async function (request, response) { // Get the client_user_id by searching for the current user const user = await User.find(...); const clientUserId = user.id; const linkTokenRequest = { user: { // This should correspond to a unique id for the current user. client_user_id: clientUserId, }, client_name: 'Plaid Test App', products: ['auth'], language: 'en', webhook: 'https://webhook.example.com', redirect_uri: 'https://domainname.com/oauth-page.html', country_codes: ['US'], }; try { const createTokenResponse = await client.linkTokenCreate(linkTokenRequest); response.json(createTokenResponse.data); } catch (error) { // handle error } }); ``` ```bash curl -X POST https://sandbox.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Plaid Test App", "user": { "client_user_id": "${UNIQUE_USER_ID}" }, "products": ["auth"], "country_codes": ["US"], "language": "en", "webhook": "https://webhook.example.com", "redirect_uri": "https://domainname.com/oauth-page.html" }' ``` ```ruby post '/api/create_link_token' do # Get the client_user_id by searching for the current user current_user = User.find(...) client_user_id = current_user.id # Create a link_token for the given user request = Plaid::LinkTokenCreateRequest.new( { user: { client_user_id: client_user_id }, client_name: 'Plaid Test App', products: ['auth'], country_codes: ['US'], language: "en", redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'), webhook: 'https://webhook.example.com' } ) response = client.link_token_create(request) content_type :json response.to_json end ``` ```java import com.plaid.client.model.Products; import com.plaid.client.model.CountryCode; import com.plaid.client.model.LinkTokenCreateRequest; import com.plaid.client.model.LinkTokenCreateRequestUser; import com.plaid.client.model.LinkTokenCreateResponse; public class PlaidExample { ... static class GetLinkToken implements HttpHandler { private static PlaidApi plaidClient; public void handle(HttpExchange t) throws IOException { // Create your Plaid client HashMap apiKeys = new HashMap(); apiKeys.put("clientId", CLIENT_ID); apiKeys.put("secret", SECRET); ApiClient apiClient = new ApiClient(apiKeys); apiClient.setPlaidAdapter(ApiClient.Sandbox); plaidClient = apiClient.createService(PlaidApi.class); // Get the clientUserId by searching for the current user User userFromDB = db.find(...); String clientUserId = userFromDB.id; LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser() .clientUserId(clientUserId); // Create a link_token for the given user LinkTokenCreateRequest request = new LinkTokenCreateRequest() .user(user) .clientName("Plaid Test App") .products(Arrays.asList(Products.fromValue("auth"))) .countryCodes(Arrays.asList(CountryCode.US)) .language("en") .redirectUri("https://domainname.com/oauth-page.html") .webhook("https://webhook.example.com"); Response response = plaidClient .linkTokenCreate(request) .execute(); // Send the data to the client return response.body(); } } } ``` ```python from plaid.model.link_token_create_request import LinkTokenCreateRequest from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser from plaid.model.products import Products from plaid.model.country_code import CountryCode @app.route("/create_link_token", methods=['POST']) def create_link_token(): # Get the client_user_id by searching for the current user user = User.find(...) client_user_id = user.id # Create a link_token for the given user request = LinkTokenCreateRequest( products=[Products("auth")], client_name="Plaid Test App", country_codes=[CountryCode('US')], redirect_uri='https://domainname.com/oauth-page.html', language='en', webhook='https://webhook.example.com', user=LinkTokenCreateRequestUser( client_user_id=client_user_id ) ) response = client.link_token_create(request) # Send the data to the client return jsonify(response.to_dict()) ``` ```go func createLinkToken(c *gin.Context) { ctx := context.Background() // Get the client_user_id by searching for the current user user, _ := usermodels.Find(...) clientUserId := user.ID.String() // Create a link_token for the given user request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId)) request.SetWebhook("https://webhook.sample.com") request.SetRedirectUri("https://domainname.com/oauth-page.html") request.SetProducts([]plaid.Products{plaid.PRODUCTS_AUTH}) resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute() // Send the data to the client c.JSON(http.StatusOK, gin.H{ "link_token": resp.GetLinkToken(), }) } ``` For the Link web integration, reinitializing Link means creating a new iframe. To avoid stacking iframes for each Link initialization, you can clean up the old iframe by calling the [destroy()](https://plaid.com/docs/link/web/index.html.md#destroy) method on the Plaid Link handler. ```javascript // Initialize Link with a new link_token each time. const configs = { token: (await $.post('/create_link_token')).link_token, onSuccess: (public_token, metadata) => { // Send the public_token to your app server. }, onExit: (err, metadata) => { // The user exited the Link flow with an INVALID_LINK_TOKEN error. // This can happen if the token expires or the user has attempted // too many invalid logins. if (err != null && err.error_code === 'INVALID_LINK_TOKEN') { linkHandler.destroy(); linkHandler = Plaid.create({ ...configs, // Fetch a new link_token because the old one was invalidated. token: (await $.post('/create_link_token')).link_token, }); } // metadata contains the most recent API request ID and the // Link session ID. Storing this information is helpful // for support. }, }; let linkHandler = Plaid.create(configs); ``` When the user is ready, they will be able to reopen Link and go through the authentication process again. --- # Link - Hosted Link for embedded clients | Plaid Docs Hosted Link for embedded clients  ================================= #### Hosted Link integration for PSPs and embedded clients  #### Overview  Some customers may not have apps themselves, but instead are embedded within other apps. For example, a payment service provider (PSP) may build a checkout flow which provides several payment options, one of which is pay by bank powered by Plaid. This checkout flow is then used by the PSP's customers within their apps. For these embedded clients, Hosted Link is the recommended approach. This guide will cover implementing [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) specifically for the embedded client use case, covering integration aspects that are unique to this scenario. While not all customers who use the embedded flow are necessarily PSPs, for the sake of readability, this guide will refer to the client that is embedded within a third party app as the PSP, and the app that they are embedded within as the merchant. Hosted Link has the following benefits for PSPs: * **Simplicity:** Hosted Link is the easiest way to integrate with Plaid when Plaid's native mobile SDKs cannot be used. * **Continuity:** With Hosted Link, Plaid manages the redirects between Plaid Link and the bank's OAuth site. Configuring redirects to a merchant app may not be possible for some PSPs, so Hosted Link ensures the Link session can be completed wherever it is opened. * **Easier access to Link callbacks and events:** When Link is launched via Plaid SDKs, Link events and metadata, including the public token, are typically returned via frontend callbacks. With Hosted Link, Link events are returned via backend API calls, making it easier to access information about the Link session without owning the frontend experience. #### Overview of Hosted Link flow for embedded clients  ##### In-app embeds  Hosted Link URLs are required to be opened in a secure context such as an `ASWebAuthenticationSession` on iOS or a Chrome Custom Tab on Android. Setting `hosted_link.is_mobile_app` to `true` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) will indicate to Plaid that Hosted Link is being opened in a secure webview, so that Plaid will use the correct redirects. ##### Webpage embeds  If the flow is embedded in a webpage, there are two options for handling the Hosted Link URI. ###### Redirecting to Hosted Link  The merchant can redirect their entire page to the Plaid Hosted Link URI. Upon the user completing Link, Plaid will redirect that webpage to the `completion_redirect_uri` provided in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. ###### Opening Hosted Link in a new window or tab  The merchant can open the Plaid Hosted Link URI in a new tab (for mobile web), or pop-up (for desktop web). This allows the user to link with Plaid while keeping the context of the checkout flow behind the pop-up. Upon completion, Plaid can close this pop-up / new tab, bringing the user back to the merchant checkout flow. #### Hosted Link integration modes  There are two main types of flows that an embedded app may use. The instructions for integrating Hosted Link will be different for each type, so to integrate with Hosted Link, you will need to identify which one your app uses. ##### With intermediary steps  In the first type of flow, with intermediary steps, an end user is taken from the merchant to an intermediary page that is controlled directly by the PSP, where they will typically pick a payment method, complete the payment, and then be returned to the intermediary page, which will redirect the end user back to the merchant. This flow provides slightly more complexity for the end customer, but does not require any additional integration work from the merchant. ##### Without intermediary steps  In the second type of flow, without intermediary steps, the end user never goes to a page controlled by the PSP. Instead, they will go directly from the merchant's app to the payment method, then return to the merchant's app. This flow is simpler from the end customer's perspective, but may require additional integration steps by the merchant. #### Integration process with intermediary steps  Follow the instructions for using [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) . In the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call, the `hosted_link.completion_redirect_uri` should be set to your website, which will then handle the process of redirecting the user back to the merchant page. #### Integration process without intermediary steps  Follow the instructions for using [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) , and see the sections below for instructions specific to the embedded client flow. ##### Completion redirect URIs  If you would like Plaid to redirect directly to the merchant app, you will use a separate `completion_redirect_uri` for each merchant, each of which must be added to the [Dashboard](https://dashboard.plaid.com/developers/api) . As an alternative, you may want the `completion_redirect_uri` to be a single URL that you host yourself, and manage the redirects back to merchant apps independently of Plaid. This way, you do not need to add each of the merchant's redirect URIs to the Plaid Dashboard. If no `completion_redirect_uri` is provided, the user will see a "Return to app" message on a Plaid.com domain in the browser and must manually navigate back to the merchant app. ###### Merchant integration steps  Because the application controls how URLs are handled, the merchant may need to add code to their app to open the Plaid hosted Link within the default browser, especially if the PSP's page is opened from within a webview. [Example function for Android](https://github.com/plaid/plaid-link-examples/blob/master/webviews/android/LinkWebview/app/src/main/java/com/example/linkwebview/MainActivity.kt#L94-L157) [Example function for iOS](https://github.com/plaid/plaid-link-examples/blob/master/webviews/wkwebview/wkwebview/LinkViewController.swift#L56-L72) --- # Link - Hosted Link | Plaid Docs Hosted Link  ============ #### Integrate with Link using a Plaid-hosted frontend  #### Overview  With Hosted Link, Plaid hosts the Link experience. Customers can use this link in web browsers or open it in a secure web context within a mobile app, eliminating the need for front-end implementation work. Hosted Link is the recommended Link mode when the official Plaid mobile or web SDKs cannot be used. This includes webview-based mobile apps, or integrations that do not fully own their frontend experience, such as [embedded payment service providers](https://plaid.com/docs/link/hosted-link/embedded-clients/index.html.md) . Hosted Link can also be used for applications where you do not have a frontend at all; for example, you can send a Hosted Link session to customers who are in-person at a retail location. (An image of "image of Hosted Link flow") Example hosted Link flow: you send a link to your customer and they complete the Plaid-hosted Link flow. You do no front-end integration work. With Link Delivery (beta), Hosted Link can also deliver the URL for the Link session to your users via text or email. To request access to Link Delivery, contact your account manager. Hosted Link is fully supported with all Plaid products and Link flows (including [update mode](https://plaid.com/docs/link/update-mode/index.html.md) ), except for Layer and Identity Verification. For Identity Verification customers, Hosted Link can optionally be used instead of IDV-specific [Verification Links](https://plaid.com/docs/identity-verification/index.html.md#verification-links-hosted-flow) to take advantage of features such as Link Delivery (beta); however, when using Hosted Link with Identity Verification, the session will not redirect to the `completion_redirect_uri`. ##### Who should use Hosted Link  Hosted Link is recommended when any of the following apply: * You are using Plaid within a webview-based mobile app. * You do not have an application frontend. * Your users are launching Link from outside an in-app context (e.g. by scanning a QR code or receiving an SMS triggered by a customer service representative). * You are launching Link from inside an iFrame or an embedded client experience where you do not control the frontend (e.g. PSP integrations). For details on using Hosted Link as an embedded client, See [Hosted Link for embedded clients](https://plaid.com/docs/link/hosted-link/embedded-clients/index.html.md) . #### Integration process  [Prefer to learn by watching? Check out this quick video guide to enabling Hosted Link!](https://www.youtube.com/watch?v=7wETps5G04A) ##### Creating a Link token  To start with Hosted Link, call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and include a `hosted_link` object in the request. The `hosted_link` object can be an empty object `{}`, or it can contain any of the `hosted_link` configuration fields. As long as you include the `hosted_link` object in your request, the `hosted_link_url` will be present in the response. Previously, Hosted Link was enabled via Plaid account managers; it is no longer necessary to request that your account manager enable Hosted Link. If your account was enabled for Hosted Link via your account manager, the `hosted_link_url` will be present in the response for all [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) requests, regardless of whether you include a `hosted_link` object. You can provide the following Hosted Link parameters to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) : * Specify a `webhook` endpoint where the `public_token` will be delivered. Webhooks are strongly recommended when using Hosted Link, as the webhook is the primary means of delivering the `public_token`, as well as of informing you when your user has completed the Link session. * To have Plaid deliver the link to your user with Link Delivery (beta), set `hosted_link.delivery_method` to either `sms` or `email`. Plaid will contact the user via the information you provide in the `user` object of the request. For example, if you selected `email`, the `user` object in the request must contain an `email_address`. * To customize the duration of the Hosted Link token lifetime, set `hosted_link.url_lifetime_seconds`. If you don't set this field, the default lifetime for Hosted Links sent by Plaid via SMS is 24 hours, and for links sent via email, it is 7 days. If Plaid isn't delivering the url, the default lifetime is 30 minutes. * To have Plaid redirect the user after they complete the Link flow, set `hosted_link.completion_redirect_uri` to the destination URI. * To indicate that the user will be opening the link in a mobile app in an `AsWebAuthenticationSession` or Android Custom Tab, set `hosted_link.is_mobile_app` to `true`. The response from [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) will include a `hosted_link_url` field. You can send a user to this URL to start the Hosted Link session. Alternatively, if your integration uses both Hosted Link and non-Hosted Link sessions, you can start a non-Hosted Link session using the `link_token` instead. In a Hosted Link session, you should also store the `link_token` value that gets returned, and make sure to associate it with the internal user ID your application is using for this user. This is the only way to make sure the data that gets returned from the Hosted Link session is associated with the right end-user. Sample /link/token/create request for Hosted Link ```bash curl -X POST https://production.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ "client_id": "${PLAID_CLIENT_ID}", "secret": "${PLAID_SECRET}", "client_name": "Wonderwallet", "country_codes": ["US"], "redirect_uri": "{{UNIVERSAL_OR_APP_LINK}}", "webhook": "https://wonderwallet.com/webhook_receiver", "language": "en", "user": { "client_user_id": "a57d3304", "phone_number": "+19162255887" }, "products": ["auth"], "hosted_link": { "delivery_method": "sms", "completion_redirect_uri": "https://wonderwallet.com/redirect", "is_mobile_app": false, "url_lifetime_seconds": 900 } } ``` Sample /link/token/create response ```json { "expiration": "2023-08-18T02:08:03Z", "hosted_link_url": "https://secure.plaid.com/link/lp9o97618r1r6p93oon62nr025950ro4s3", "link_token": "link-production-4b42163e-6e1c-48bb-a17a-e570405eb9f8", "request_id": "kNbPMmLxzBObzpt" } ``` ##### Obtaining a public token  In most other Plaid integration methods, upon completion of the Link flow, your frontend code would receive either an `onSuccess` or `onExit` callback. In Hosted Link, there is no frontend integration required (or possible). You will instead receive information about the Link flow (including the `public_token`) via the [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) webhook and the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint. Each time a user completes a Link flow, Plaid will fire a [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) webhook that contains information about what caused the session to end, as well as the public token if the session completed successfully. In flows where Link is re-initialized after an OAuth redirect, this webhook will fire exactly once, after the user completes the entire Link flow. Sample SESSION\_FINISHED webhook ```json { "webhook_type": "LINK", "webhook_code": "SESSION_FINISHED", "status": "SUCCESS", "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171", "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176", "public_tokens": [ "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" ], "environment": "sandbox" } ``` You can also call [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) with the relevant Link token to receive more detailed metadata on sessions started using this Link token. Each Link session includes the time it was started, and (if applicable) the time it finished. Each completed Link session also includes the metadata that would normally be passed to the `onSuccess` or `onExit` callbacks, including the `public_token` for successful sessions. Detailed session data, including the public token, will also be available from [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) for six hours after the session has completed. In general, it is recommended to use the webhook to obtain the public token, since it will allow you to get the public token more promptly, but you may want to use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) if your integration does not use webhooks, or as a backup mechanism if your system missed webhooks due to an outage. In [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) the `public_token` is present in both the `on_success` object and the `results` object. It is recommended to use the `results` object, as the older `on_success` object does not support the newer [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) option, which allows for multiple public tokens to be returned in a single Link session. Sample /link/token/get response ```json { "created_at": "2024-07-29T21:22:13Z", "expiration": "2024-07-29T21:52:13Z", "link_sessions": [ { "events": [ { "event_id": "c1ccb962-9de0-494c-b85b-e89cdf3b2478", "event_metadata": { "institution_id": "ins_10", "institution_name": "American Express", "request_id": "Z9MB4fuMB2TJqgL" }, "event_name": "HANDOFF", "timestamp": "2024-07-29T21:23:03Z" }, { "event_id": "ff03f1ff-313b-4c2e-997f-83791c7ec432", "event_metadata": { "institution_id": "ins_10", "institution_name": "American Express", "request_id": "vyPamzbGPPsQucO" }, "event_name": "OPEN_OAUTH", "timestamp": "2024-07-29T21:22:34Z" }, { "event_id": "0ea6d0df-1bb0-4e4d-bea5-b3731b7536bf", "event_metadata": { "institution_id": "ins_10", "institution_name": "American Express", "request_id": "vyPamzbGPPsQucO" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T21:22:33Z" }, { "event_id": "e14c7b49-82c4-4f0c-a88a-987a62241d34", "event_metadata": { "institution_id": "ins_10", "institution_name": "American Express", "request_id": "0jjsLDlMl1VaVxU" }, "event_name": "SELECT_INSTITUTION", "timestamp": "2024-07-29T21:22:32Z" }, { "event_id": "b9b9f7ce-52bc-470e-801b-b4fa1da98e59", "event_metadata": { "request_id": "0jjsLDlMl1VaVxU" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T21:22:23Z" }, { "event_id": "e057a92c-eff8-467c-92c2-620109207e87", "event_metadata": { "request_id": "aHnAMiUzk8HrsNn" }, "event_name": "SKIP_SUBMIT_PHONE", "timestamp": "2024-07-29T21:22:22Z" }, { "event_id": "f1feedc9-61be-4a42-885c-cb67511473d2", "event_metadata": { "request_id": "aHnAMiUzk8HrsNn" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T21:22:21Z" }, { "event_id": "f9b49b0b-4259-4a32-860b-653b55ff8736", "event_metadata": { "request_id": "CGTlWrGRd8WaGa2" }, "event_name": "TRANSITION_VIEW", "timestamp": "2024-07-29T21:22:20Z" } ], "finished_at": "2024-07-29T21:23:03.326860787Z", "link_session_id": "f3c3b8fe-16c6-4670-8f2b-e8d797aa6e9f", "on_success": { "metadata": { "accounts": [ { "class_type": null, "id": "d1rVJdbe1jCE9jE81wlduPlQQejKXeCJnDzyw", "mask": "3333", "name": "Plaid Credit Card", "subtype": "credit card", "type": "credit", "verification_status": null } ], "institution": { "institution_id": "ins_10", "name": "American Express" }, "link_session_id": "f3c3b8fe-16c6-4670-8f2b-e8d797aa6e9f", "transfer_status": null }, "public_token": "public-sandbox-d1e64436-f033-4302-a469-b90656edf8c7" }, "results": { "item_add_results": [ { "accounts": [ { "class_type": null, "id": "d1rVJdbe1jCE9jE81wlduPlQQejKXeCJnDzyw", "mask": "3333", "name": "Plaid Credit Card", "subtype": "credit card", "type": "credit", "verification_status": null } ], "institution": { "institution_id": "ins_10", "name": "American Express" }, "public_token": "public-sandbox-d1e64436-f033-4302-a469-b90656edf8c7" } ] }, "started_at": "2024-07-29T21:22:17.0951134Z" } ], "link_token": "link-sandbox-9b48eb4c-7e1b-44e1-b80d-faa1d71cdf5e", "metadata": { "client_name": "Wonderwallet", "country_codes": [ "US" ], "initial_products": [ "transactions" ], "language": "en", "redirect_uri": null, "webhook": "https://webhook.site/dc9c138f-75de-4db1-883a-a4add4b7eb7e" }, "request_id": "jBBxxNC842EJNqW" } ``` #### Link session events  To obtain Link session events while using Hosted Link, listen for the [EVENTS](https://plaid.com/docs/api/link/index.html.md#events) webhook, or use [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) . #### Integrating Hosted Link in native mobile applications  If you are unable to use the Plaid Link SDK in your native mobile app, creating and opening up a Hosted Link is a stable and reliable way of taking users through the Link process. We recommend using a Hosted Link instead of trying to use the Plaid Web SDK in a webview. When you use a Hosted Link in a native mobile app, you will open the URL inside of an "out of process" webview, such as an `ASWebAuthenticationSession` in iOS, or an Android Custom Tab. These sessions appear as part of your application, making the process feel more seamless than opening up the URL in a separate browser application. When the Link session is complete, Plaid will attempt to open a `completion_redirect_uri` that you specify. This is typically a URI with a custom scheme that automatically closes the web session and allows your application to continue from where you left off. To use Hosted Link in a native mobile application: ##### Create a Link token  Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with the following values: * `hosted_link.is_mobile_app` should be set to `true` * `hosted_link.completion_redirect_uri` should be a URI with a custom scheme. * This scheme can be any value you'd like, as long as it isn't a reserved one such as `http` or `tel`. By convention, it's often one associated with the name of your application. * For example, your app might have something like `wonderwallet://hosted-link-complete` as a completion redirect URI. * Unlike the `redirect_uri` value, this URI does not need to be registered with the Plaid Dashboard, nor does it need to point to a "real" location. * `redirect_uri` should ideally be a URL that opens up your native mobile application, such as a Universal Link on iOS or an Android App Link on Android. * The `redirect_uri` is used in situations where Plaid opens up another mobile app, like Chase, for app-to-app authentication. * When the user is done authenticating with the third party app, the app will attempt to open this URI, which should redirect users back into your app. * Plaid cannot use `android_package_name` to perform the OAuth redirect when using Hosted Link. You must use `redirect_uri`, even if using an Android app. * There is nothing you need to do to handle this incoming `redirect_uri`. As long as the link opens your application, the Hosted Link session can take it from there. Sample /link/token/create request for mobile apps ```bash curl -X POST https://production.plaid.com/link/token/create \ -H 'Content-Type: application/json' \ -d '{ ...Other data removed... hosted_link: { completion_redirect_uri: "wonderwallet://hosted-link-complete", is_mobile_app: true }, redirect_uri: "https://mysite.com/universal-link/jump-to-my-app.html", }' ``` ##### "Register" your custom URL scheme  You will need to make sure your operating system can handle the completion redirect URI that the Hosted Link session will open when it's complete. On iOS, all you need to do is pass this URL scheme into the `ASWebAuthenticationSession` when you initialize it (see [Open the Hosted Link URL](https://plaid.com/docs/link/hosted-link/index.html.md#open-the-hosted-link-url) ). There is no need to register this URL scheme in your Xcode project in any other way. In Android, you should create an Intent Filter for the activity that you want to appear when the user is done with the session. Sample Android Manifest snippet ```html ``` If this activity is the same activity that you used to launch Hosted Link in the first place, you may want to give this activity a `singleTask` or `singleTop` launch mode, so that the original activity "pops back" to the top of your application, and you're not creating multiple copies of the same activity. ##### Open the Hosted Link URL  On iOS, create an `ASWebAuthenticationSession`, using the Hosted Link URL you received from the server and the same custom scheme you used in your `completion_redirect_uri`. Sample call starting ASWebAuthenticationSession in Swift ```swift @IBAction func connectBankWasPressed(_ sender: Any) { guard let hostedLinkURL = hostedLinkURL else {return} let scheme = "wonderwallet" let session = ASWebAuthenticationSession(url: URL(string: hostedLinkURL)!, callbackURLScheme: scheme) { callbackURL, error in guard error == nil, let callbackURL = callbackURL else { // The user might have clicked "Cancel" on the session. This will be captured as a 'canceledLogin' error. return } if (callbackURL.absoluteString == "\(scheme)://hosted-link-complete") { self.checkLinkStatus() } } session.presentationContextProvider = self session.start() } ``` For the above code to work, you will also need to make sure the appropriate view controller is set as a proper context provider: Setting a context provider in UIKit ```swift extension ConnectToBankViewController: ASWebAuthenticationPresentationContextProviding { func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor { return view.window! } } ``` On Android devices, create a Custom Tab that opens up the Hosted Link URL from within your application: Creating a Custom Tab example in Kotlin ```kotlin import androidx.browser.customtabs.CustomTabsIntent import android.net.Uri private fun openHostedLink(hostedLinkUrl: String) { val customTabsIntent = CustomTabsIntent.Builder().build() customTabsIntent.launchUrl(this, Uri.parse(hostedLinkUrl)) } ``` See the [Apple Developer Documentation](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession) or [Chrome Developer Documentation](https://developer.chrome.com/docs/android/custom-tabs) for more details on these two methods. ##### Handle the incoming URI  When the user is done with the Hosted Link session, Plaid will attempt to open the `completion_redirect_uri` you specified when creating the Link token. If your application is set up as described above, this will close the Hosted Link page and bring your application back to the foreground. You will then receive this URI in a callback handler, where you can perform tasks such as refreshing the user's Link Session status. The `completion_redirect_uri` is not supported in Identity Verification sessions. Note that Plaid will call this URI whether the user successfully completed the session, or asked Plaid to exit the connection process, so you cannot assume that receiving this URI means a successful connection. You should listen for the [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) webhook or call [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to determine the status of the user's Hosted Link session. On iOS, you define this handler when you create the `ASWebAuthenticationSession` Sample callback handler in ASWebAuthenticationSession ```swift let scheme = "wonderwallet" let session = ASWebAuthenticationSession(url: URL(string: hostedLinkURL)!, callbackURLScheme: scheme) { callbackURL, error in guard error == nil, let callbackURL = callbackURL else { return } if (callbackURL.absoluteString == "\(scheme)://hosted-link-complete") { self.checkLinkStatus() } } ``` If the user dismisses the window by clicking the Cancel button, this handler will still be called, but with a `canceledLogin` error instead of a `callbackURL`. On Android, you can retrieve this URL in the `onNewIntent` callback if you are returning to the previous activity. (If you are opening a new activity, you can use the `onCreate` callback.) Sample capturing the incoming URI in onNewIntent ```kotlin override fun onNewIntent(intent: Intent?) { super.onNewIntent(intent) intent?.data?.let { uri -> if (uri.scheme == "wonderwallet" && uri.host == "hosted-link-complete") { checkLinkStatus() } } } ``` If the user dismisses the Custom Tab by tapping the close button, this callback will not be called, but an `onResume` callback will still be called. #### Migrating to Hosted Link from other integrations  First, review the [Integration process](https://plaid.com/docs/link/hosted-link/index.html.md#integration-process) to understand how to launch the Hosted Link flow and the configuration options available. If you're currently capturing Link session events, migrate to using [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) to receive Link session events. If your users will be opening Link sessions inside a native mobile application, launch Hosted Link in an out-of-process webview as described above instead of using an in-process webview. ##### iFrame based nested integrations  For nested integrations like iFrames in a customer web page within a merchant webview, shift from capturing events through redirects to using backend events via [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) . Your merchants should launch Hosted Link in an out-of-process webview or external browser. Either you or the merchant must add an extra callback parameter to [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , allowing Plaid to close the out-of-process webview as needed. You will likely make the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call. Merchants must either obtain a callback from the customer or ensure handling of a specified callback in their code. ##### Next steps  Once you have obtained a public token, you can integrate via the same process as non-Hosted Link integrations, including calling [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the public token for an access token. #### Testing Hosted Link  You can test Hosted Link in Production or Sandbox. In the Sandbox environment, Plaid will not provide email or SMS Hosted Link delivery, and update mode sessions will expire after 30 minutes. #### Pricing  When using Link Delivery to deliver Hosted Link sessions, there is a fee for each link sent. For Link Delivery pricing details, [contact sales](https://plaid.com/contact/) or your account manager. --- # Link - Overview | Plaid Docs Link overview  ============== #### Use Link to connect to your users' financial accounts with the Plaid API  #### Introduction to Link  Plaid Link is the client-side component that your users will interact with in order to link their accounts to Plaid and allow you to access their accounts via the Plaid API. Using Link is mandatory for all Plaid integrations, except for ones using only the handful of products that do not require end user interaction, such as [Enrich](https://plaid.com/docs/enrich/index.html.md) or the [Identity Verification backend only-flow](https://plaid.com/docs/identity-verification/index.html.md#data-source-checks-without-ui-backend-flow) . An example Link flow. Your exact flow may differ. (An image of "An example Link flow. Your exact flow may differ.") (An image of "...the user selects their bank...") (An image of "...is directed to its OAuth flow...") (An image of "...signs in via OAuth...") (An image of "...selects which accounts to share...") (An image of "...and links their account!") (An image of "In the guest flow, they can optionally save their account for fast access next time.") (An image of "Once the phone number is verified, Link will close automatically.") Plaid Link handles all aspects of the login and authentication experience, including credential validation, multi-factor authentication, error handling, and sending account linking confirmation emails. For institutions that use OAuth, Link also manages the OAuth handoff flow, bringing the user to their institution to log in, and then returning them to the Plaid Link experience within your app. To try Link, see [Plaid Link Demo](https://plaid.com/demo/) . Link is the only available method for connecting accounts and authenticating users in Production. In the Sandbox test environment, Link can optionally be bypassed for testing purposes via [/sandbox/public\_token/create](https://plaid.com/docs/api/sandbox/index.html.md#sandboxpublic_tokencreate) . #### Link supported platforms and presentation modes  | For... | Use... | | --- | --- | | Best mobile UX | Native [iOS](https://plaid.com/docs/link/ios/index.html.md) , [Android](https://plaid.com/docs/link/android/index.html.md) , or [React Native](https://plaid.com/docs/link/react-native/index.html.md) SDKs | | Best web UX | [Native web SDK](https://plaid.com/docs/link/web/index.html.md) (also available with React wrapper) | | Webviews, iFrames, no frontend, or embedded flows where you don't control the frontend | [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) | There are also two optional Link presentation modes you can enable. | For... | Use... | | --- | --- | | Driving the most end users to choose Plaid | [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) | | Linking multiple banks in a single session (e.g. for PFM use cases) | [Multi-Item Link](https://plaid.com/docs/link/multi-item-link/index.html.md) | #### Customizing and optimizing Link  You can customize parts of Link's flow straight from the [Dashboard](https://dashboard.plaid.com/link) . You can preview your changes in real time and then publish them instantly once you're ready to go live. For more details, see [Link customization](https://plaid.com/docs/link/customization/index.html.md) . To help you take advantage of the options available for customizing and configuring Link, Plaid offers a [Link best practices guide](https://plaid.com/docs/link/best-practices/index.html.md) and an [in-app messaging guide](https://plaid.com/docs/link/messaging/index.html.md) for advice on how to present Link within your app. #### Initializing Link  Link is initialized by passing the `link_token` to Link. The exact implementation details for passing the `link_token` will vary by platform. For detailed instructions, see the page for your specific platform: [web](https://plaid.com/docs/link/web/index.html.md) , [iOS](https://plaid.com/docs/link/ios/index.html.md) , [Android](https://plaid.com/docs/link/android/index.html.md) , [React Native](https://plaid.com/docs/link/react-native/index.html.md) , [mobile webview](https://plaid.com/docs/link/webview/index.html.md) , or [Plaid-hosted](https://plaid.com/docs/link/hosted-link/index.html.md) . For recommendations on configuring the `link_token` for your use case, see [Choosing how to initialize products](https://plaid.com/docs/link/initializing-products/index.html.md) . #### Link flow overview  Most Plaid products use Link to generate `public_tokens`. The diagram below shows a model of how Link is used to obtain a `public_token`, which can then be exchanged for an `access_token`, which is used to authenticate requests to the Plaid API. Note that some products (including Plaid Check, Identity Verification, Monitor, Document Income, and Payroll Income) do not use a `public_token` or `access_token`. For those products, you will call product endpoints once the end user has completed Link; see product-specific documentation for details on the flow. **The Plaid flow** begins when your user wants to connect their bank account to your app. (An image of "Step diagram") **1**Call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) to create a `link_token` and pass the temporary token to your app's client. (An image of "Step 1 diagram") **2**Use the `link_token` to open Link for your user. In the [onSuccess callback](https://plaid.com/docs/link/web/index.html.md#onsuccess) , Link will provide a temporary `public_token`. This token can also be obtained on the backend via `/link/token/get`. (An image of "Step 2 diagram") **3**Call [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) to exchange the `public_token` for a permanent `access_token` and `item_id` for the new `Item`. (An image of "Step 3 diagram") **4**Store the `access_token` and use it to make product requests for your user's `Item`. (An image of "Step 4 diagram") In code, this flow is initiated by creating a `link_token` and using it to initialize Link. The `link_token` can be configured with the Plaid products you will be using and the countries you will need to support. Once the user has logged in via Link, Link will issue a `public_token`. You can obtain the `public_token` through either the frontend or the backend: * On the frontend: From the client-side `onSuccess` callback returned by Link after a successful session. For more details on this method, see the Link frontend documentation for your specific platform. * On the backend: From the [/link/token/get](https://plaid.com/docs/api/link/index.html.md#linktokenget) endpoint or opt-in [SESSION\_FINISHED](https://plaid.com/docs/api/link/index.html.md#session_finished) webhook after the Link session has been completed successfully. For more details on this method, see the [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) documentation. The `public_token` can then be exchanged for an `access_token` via [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) . #### Error-handling flows  If your application will access an Item on a recurring basis, rather than just once, it should support [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . Update mode allows you to refresh an Item if it enters an error state, such as when a user changes their password or MFA information. For more information, see [Updating an Item](https://plaid.com/docs/link/update-mode/index.html.md) . It's also recommended to have special handling for when a user attempts to link the same Item twice. Requesting access tokens for duplicate Items can lead to higher bills and end-user confusion. To learn more, see [preventing duplicate Items](https://plaid.com/docs/link/duplicate-items/index.html.md) . Occasionally, Link itself can enter an error state if the user takes over 30 minutes to complete the Link process. For information on handling this flow, see [Handling invalid Link tokens](https://plaid.com/docs/link/handle-invalid-link-token/index.html.md) . #### Supporting OAuth  Many institutions use an OAuth authentication flow, in which Plaid Link redirects the end user to their bank's website or mobile app to authenticate. To learn more, see the [OAuth guide](https://plaid.com/docs/link/oauth/index.html.md) . #### Returning user flows  The returning user flow allows you to enable a faster Plaid Link experience for your users who already use Plaid. To learn more, see [Returning user experience](https://plaid.com/docs/link/returning-user/index.html.md) . #### Troubleshooting  Since all your users will go through Link, it's important to build as robust an integration as possible. For details on dealing with common problems, see the [Troubleshooting](https://plaid.com/docs/link/troubleshooting/index.html.md) section. #### Link updates  Plaid periodically updates Link to add new functionality and improve conversion. These changes will be automatically deployed. Any test suites and business logic in your app should be robust to the possibility of changes to the user-facing Link flow. Users of Plaid's SDKs for React, React Native, iOS, and Android should regularly update to ensure support for the latest client platforms and Plaid functionality. --- # Link - Choosing when to initialize products | Plaid Docs Choosing how to initialize products  ==================================== #### Increase conversion and reduce costs by learning how to configure products in Link  #### Overview  When you create a Link token, you specify which products to initialize Link with by including those products in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request. Which products you specify in the request parameters will impact many aspects of your Plaid integration, including user conversion, institution availability, the latency your user experiences when connecting their accounts in Link, the latency you experience when retrieving data from the API, and which products you will be billed for. You can also add products to an Item post-Link, which is discussed below. [Watch video](https://www.youtube.com/watch?v=yPQPPGdBYIs) #### Initializing products during Link  The table below summarizes the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request parameters that determine product initialization in Link: | Parameter | Required? | Summary | Will Link restrict institutions? | When will Plaid bill me? | | --- | --- | --- | --- | --- | | products | Yes | The user must connect an applicable institution and account. Item creation will fail if one or more listed products is unavailable at the institution, incompatible with the account type, or experiences an extraction error. Use this for products that are essential for your use case. | Yes. Only institutions that support all products in this array will be available in Link. | For products billed under a [one-time or subscription fee](https://plaid.com/docs/account/billing/index.html.md) model, you will be billed upon Item creation. | | required if supported products | No | If the institution supports the products and an applicable account is selected, Plaid will attempt to get data for all of these products, and Item creation will fail if Plaid experiences an extraction error. If the institution or selected account _doesn't_ support these products, they will be ignored and Item creation will succeed. Use this for products if you don't want to let users opt out (e.g. for products that are part of your anti-fraud checks, like Identity) but you don't want to block users whose institutions don't support these products. | No | For products billed under a [one-time or subscription fee](https://plaid.com/docs/account/billing/index.html.md) model, you will be billed upon Item creation. | | optional products | No | Plaid will attempt to get data for these products, but if this fails or the institution or selected account type doesn't support one or more of these products, Item creation will still succeed. Use this if the product is a "nice to have" for your use case but you are willing to let end users opt out. | No | For Auth, Identity, and Plaid Check products, you will only be billed if you use the product. For other products billed under a [one-time or subscription fee](https://plaid.com/docs/account/billing/index.html.md) model, you will be billed upon Item creation. | | additional consented products | No | Plaid will collect the user's consent to retrieve this data so that if you decide to use this product later on, you won't need to collect the user's consent again. Plaid will not extract data for these products and Item creation will not fail if the products are unavailable or incompatible. Use this for products you don't need immediately but may need later (e.g. based on your user's journey within your app or planned additions to your Plaid integration). | No | When you call the product endpoint for the first time | #### Adding products post-Link  If a product was not initialized during Link, calling an endpoint for that product will automatically attempt to add that product to the Item. For example, if an Item was not initialized with Transactions during Link, calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) or [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) on that Item for the first time will attempt to add the Transactions product to the Item. Data Transparency Messaging is automatically enabled for all new customers' US and Canada-based Link sessions as of October 2024. On an Item enabled for [Data Transparency Messaging](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md) , you can only add products by calling an endpoint if you specified those products in the Additional Consented Products array when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , or if you already have the required [permissions scopes](https://plaid.com/docs/link/data-transparency-messaging-migration-guide/index.html.md#data-scopes-and-consent) for those products. As another example, if the Item is at an OAuth institution that requires users to grant product-specific access, the end user will need to have granted that access to that product during the OAuth consent flow. To require that users provide all OAuth consent necessary to use a secondary product, use [Required if Supported Products](https://plaid.com/docs/link/initializing-products/index.html.md#required-if-supported-products) instead of adding the product by calling its endpoint post-Link. If you do not have all the consent required to add a product, your API call attempting to add the product will fail and you will need to send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) to obtain that consent. Some additional exceptions to the post-Link product add flow exist: * Identity Verification and Payment Initiation cannot be added post-Link. * Assets, Statements, and Bank Income can only be added post-Link via the update mode flow. * If the Item contains a [limited-purpose checking account](https://plaid.com/docs/auth/index.html.md#enabling-limited-purpose-checking-accounts-for-rent-or-mortgage) and `auth` was not listed as an `optional_product` or `additional_consented_product`, Auth can only be added via [Update Mode](https://plaid.com/docs/link/update-mode/index.html.md) . (This is not common, and can only occur if you have explicitly opted in to allowing limited-purpose checking accounts.) #### Impacts of product initialization on latency  If you initialize Link with a product in the Products, Required if Supported Products, or Optional Products array, Plaid will prepare relevant product data during or immediately after Link. Otherwise, Plaid will only begin to fetch data for that product when you call an endpoint for that product, such as [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) or [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . You can minimize product latency by initializing Link with a given product, as opposed to adding the product to the item post-Link. Products that retrieve extended account history, such as Transactions and Investments, may take a minute or longer to prepare. If you specify one of these products when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , and then you add another product immediately after the user has exited Link, you may experience higher latency when calling the secondary product because the first product is still being prepared. You can avoid this problem by including the secondary product as either an Optional Product or Required if Supported Product when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , which allows Plaid to optimize how product data is prepared. #### Impacts of product initialization on billing  If you initialize Link with a product that is billed under a [one-time or subscription fee](https://plaid.com/docs/account/billing/index.html.md) model (such as Auth, Identity, Income, Investments, Liabilities, or Transactions) you will be billed when the Item is created, even if you are not yet using the product's endpoints. There are exceptions: * If you specify Auth, Identity, and/or Signal in the Optional Products array, you will not be billed for them until you use their endpoints (e.g., [/auth/get](https://plaid.com/docs/api/products/auth/index.html.md#authget) ). * You will not be billed for any products in the Additional Consented Products array until you use their endpoints. * Investments has two different subscriptions that can be associated with it: Investments Holdings and Investments Transactions. Initializing Link with Investments adds only Investments Holdings; the Investments Transactions subscription will not be added until you call [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) for the first time on the Item. Note that Plaid will still pre-fetch investment transaction history when you initialize with Investments, even though you are not yet being billed for Investments Transactions. To avoid unwanted charges, do not initialize Link with a one-time or subscription fee product in Production unless you are sure you are going to use that product. This instruction applies to the Products, Required if Supported Products, and Optional Products arrays, with the exception of Auth, Identity, and Signal Transaction Scores when used as Optional Products. To learn more about how Plaid bills each product, see [Billing](https://plaid.com/docs/account/billing/index.html.md) . #### Impacts of product initialization on conversion  The products you specify in the Products array will determine which institutions and accounts are available in Link. If you specify multiple products in the Products array, only institutions and accounts supporting _all_ of those products will be available. See the [accounts / product support](https://plaid.com/docs/api/accounts/index.html.md#account-type--product-support-matrix) matrix to learn which account types support which products. To avoid overly restricting the institution and account list, you can use the [Required if Supported Products](https://plaid.com/docs/link/initializing-products/index.html.md#required-if-supported-products) or [Optional Products](https://plaid.com/docs/link/initializing-products/index.html.md#optional-products) features, or initialize Link with only your required products in the Products array and then call your other products' endpoints later. ##### Non-connection based Auth  Because non-connection-based Auth methods (Database Auth, Same-Day Micro-deposits, and Instant Micro-deposits) limit an Item's ability to be used with other products, initializing with any product other than `auth` in the `products` array will disable the use of non-connection-based Auth methods, which may impact conversion. To retain the ability to use these alternative Auth verification methods, include other products in the `optional_products` or `required_if_supported_products` array. For more details, see [Expanding Auth coverage](https://plaid.com/docs/auth/coverage/index.html.md) . ##### Signal and the institution list  Because Signal Transaction Scores will function even if not all of the 80+ core attributes can be calculated, and because Balance is supported at all relevant financial institutions, including `signal` in the `products` array will never limit the list of available institutions. If `signal` is included in the `products` array, `auth` must also be included in the `products` array. #### Required if Supported Products  Using the `required_if_supported_products` parameter with a Plaid client library requires the following client library minimum versions: Node: 14.1.0, Python: 14.1.0, Ruby: 19.1.0, Java: 15.1.0, Go: 13.0.0. You may want to require one or more secondary products when possible, but avoid excluding users whose financial institution doesn't support those products. To do this, specify the secondary products in the Required if Supported Products array. When a product is specified in the Required if Supported Products array, Plaid will require that product if possible. If the institution the end user is attempting to link supports the secondary product, and the user grants Plaid access to an account at the institution that is compatible with it, Plaid will treat the product as though it was specified in the Products array. If the institution doesn't support the product, if the user doesn't have accounts compatible with it, or if the user has compatible accounts but doesn't grant access to them, Plaid will ignore the product. (To determine whether a product was successfully added to the Item, you can call [/item/get](https://plaid.com/docs/api/items/index.html.md#itemget) after obtaining your access token and read the Item's Products array.) For example, if you initialize Link with both Auth and Identity in the Products array, a user will only be able to link an account if both Auth and Identity are supported by their institution, and they will not be able to use flows like Same-day Micro-deposits that require Auth to be initialized by itself. But if you specify Auth in the Products array and Identity in the Required if Supported Products array, users will be able to link checking and savings accounts at any institution that supports Auth, even if the institution does not support Identity. They will also be able to access flows that require Auth to be initialized by itself, like Same-day Micro-deposits. If the institution _does_ support both Auth and Identity, Plaid will attempt to initialize the Item with both products. If the institution has an OAuth flow where Identity access can be configured as a separate permission, and the user does not grant access to Identity, the Link attempt will error and the user will be prompted to retry the OAuth flow. As another example, if Transactions and Auth are both specified in the Products array, users will only be able to link checking or savings accounts, because specifying Auth limits acceptable accounts to checking and savings accounts. However, if Transactions is specified in the Products array and Auth is specified in the Required if Supported Products array, users will be able to link other Transactions-compatible account types, such as credit cards and money market accounts. If they do link a checking or savings account, Plaid will fetch Auth data for that account. #### Optional Products  Using the `optional_products` parameter with a Plaid client library requires the following client library minimum versions: Node: 17.0.0, Python: 17.0.0, Ruby: 23.0.0, Java: 18.0.0, Go: 17.0.0. Optional Products is similar to Required if Supported Products, except that products specified in the Optional Products array are treated as _best-effort_. If an institution supports the selected products but they cannot be added to the Item (e.g., because of a temporary institution error impacting only some products, or because the user did not grant the required product-specific OAuth permissions), Item creation will succeed in spite of these failures. Like the Required if Supported Products array, the Optional Products array does not affect institution filtering or account filtering, which means there are no guarantees around product data availability. For example, if you initialize Link with Transactions in the Products array and Auth in the Optional Products array, the Item is guaranteed to support Transactions, but it will also allow linking account types that are incompatible with Auth, like credit cards. Unlike Required if Supported Products, Optional Products will not fail the Link attempt if the necessary OAuth permissions are not granted. If the user does not grant access to the data needed to support an Optional Product in the OAuth linking flow, they will not be required to go through the OAuth flow again to update their permissions. Instead, the Item will be successfully created and the Optional Product will be unavailable until you have prompted the user to fix their permissions via [Update Mode](https://plaid.com/docs/link/update-mode/index.html.md) . If Auth is specified in the Optional Products array, Auth will only be added to the Item if the institution supports [Instant Auth](https://plaid.com/docs/auth/coverage/instant/index.html.md) . If you specify Auth, Identity, or Plaid Check (CRA) products in the Optional Products array, you will only be billed for these products if you call their endpoints. #### When to use Required if Supported Products  If your only reason for omitting a product from the Products array is to increase the number of institutions covered, you should specify the product in the Required if Supported Products array rather than adding the product by calling its endpoint. Initializing both products during Link will make it easier to obtain the consent required at institutions that use OAuth, because the user will be prompted to fix their selections during the OAuth flow if they do not grant the required consent for all products. Initializing both products upfront can also reduce latency, because it allows Plaid to begin fetching data immediately and to optimize the order in which different types of data are requested. For example, one common pattern for payments customers is to use Auth in the Products array, and Identity in the Required if Supported Products array. This means you will get Identity coverage for all accounts where it's available, but you won't block customers from linking their accounts if their institution doesn't support Identity. Required if Supported Products is recommended over Optional Products if it is important to your use case that your user not be able to link an account if they've opted out of using certain products in the OAuth flow. For example, if you're accepting ACH payments, you might not want to let a user link their account while opting out of products used for risk mitigation, like Identity or Signal Transaction Scores. #### When to use Optional Products  If you think that you may want to use Auth, Identity, and/or Signal Transaction Scores for an Item, but it isn't necessary for all users, you should specify the product in the Optional Products array, because doing so will allow Plaid to pre-load required data for improved performance. For Auth and Identity, this means lower latency. In the case of Signal Transaction Scores, this means improved accuracy, as Signal Transaction Scores is designed to optimize for latency over accuracy when a tradeoff is necessary. As an example of when to use the Optional Products array, if your app primarily uses Transactions for budgeting but also uses Auth to transfer funds for a small percentage of users (e.g., paid users), you should specify Transactions in the Products array and Auth in the Optional Products array. This will ensure that all Items support Transactions, while also ensuring that Plaid will collect Auth data for as many users as possible without affecting Link conversion or increasing your Auth bill. As an example of when _not_ to use the Optional Products array, if your app primarily uses Auth for funds transfers but also offers an optional budgeting add-on that uses Transactions, you should specify Auth in the Products array and Transactions in the Additional Consented Products array, and then add Transactions to the Item by calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) only once your user opts in to using the budgeting tool. This will prevent you from being billed for Transactions before you are sure you need to use it. #### Special cases for Link initialization  There are some exceptions to the ability to initialize consented products by calling their endpoints: * Bank Income and Assets can both be initialized post-Link, but may require re-launching Link to obtain additional consent. See [Verifying Bank Income for existing Items](https://plaid.com/docs/income/bank-income/index.html.md#verifying-bank-income-for-existing-items) and [Adding Assets to existing Items](https://plaid.com/docs/assets/index.html.md#getting-an-asset-report-for-an-existing-item) . * Identity Verification and Payment Initiation cannot be initialized post-Link. * When Auth is initialized post-Link, the main Instant Auth flow can be used, but the less common Instant Match, Automated Micro-deposits, or Same Day Micro-deposits flows cannot be initialized post-Link, as these are interactive flows that require user input. Some products have limitations on being initialized alongside other products in the same Link session: * Plaid Check products (such as Consumer Report) cannot be initialized in the same Link session as Assets or Income Verification. * To use Same Day Micro-deposits, Instant Micro-deposits, Database Auth, Database Insights, or Database Match, Auth must be the only product in the `products` array when initializing Link. However, you can add Signal Transaction Scores or Identity to these Items via the `optional_products`, `required_if_supported_products`, or `additional_consented_products` fields. * Income can only be initialized alongside other products if using Bank Income; Payroll Income and Document Income cannot be initialized alongside other products. * Identity Verification and Payment Initiation cannot be initialized alongside any other products. If you need to use these products along with other Plaid products, your user will need to launch the Link flow a second time. #### Recommendations for initializing Link with specific product combinations  ##### Auth with Identity and/or Signal Transaction Scores  Initialize Link with Auth and Signal in the Products array and Identity in the Required if Supported Products array. Specifying Identity in the Required if Supported Products array will increase conversion while minimizing latency when calling Identity endpoints. For most use cases, it is recommended to put Identity in Required if Supported Products instead of Optional Products. Using Optional Products for Identity allows customers at some OAuth institutions to opt out of sharing identity data and still complete the Link flow. Bad actors are likely to opt out of data sharing, reducing the usefulness of Identity as a fraud detection tool. If you are willing to take on more risk, you can initialize with Identity in the Optional Products array instead, which will increase conversion and prevent you from being billed for Identity when you don't use it. If Signal is in the Products array, Auth _must_ also be in the Products array. If you initialize with `signal` in the `additional_consented_products` array, you will need to call [/signal/prepare](https://plaid.com/docs/api/products/signal/index.html.md#signalprepare) before calling [/signal/evaluate](https://plaid.com/docs/api/products/signal/index.html.md#signalevaluate) for the first time on an Item in order to get the most accurate results. For more details, see [Adding Signal to existing Items](https://plaid.com/docs/signal/creating-signal-items/index.html.md#adding-signal-to-existing-items) . ##### Auth with Assets  Initialize Link with Assets in the Products array and Auth in the Required if Supported Products array. This will allow your user to link any account type, not just checking or savings accounts, which is important for getting their full financial picture. ##### Transactions with Auth and/or Identity  If Transactions is the primary product, initialize with Transactions in the Products array, Auth in the Optional Products array, and Identity in the Required if Supported Products array. This will reduce latency when calling the Auth and/or Identity endpoints while maximizing institution coverage. It will also prevent you from being charged for Auth unless you end up calling its endpoints. For most use cases, it is recommended to put Identity in Required if Supported Products instead of Optional Products. Using Optional Products for Identity allows customers at some OAuth institutions to opt out of sharing identity data and still complete the Link flow. Bad actors are likely to opt out of data sharing, reducing the usefulness of Identity as a fraud detection tool. If you are willing to take on more risk, you can initialize with Identity in the Optional Products array instead, which will increase conversion and prevent you from being billed for Identity when you don't use it. ##### Transactions with Liabilities and/or Investments  For personal finance use cases, initialize Link with Transactions, with Liabilities and Investments in the Additional Consented Products array. Then call Liabilities or Investments endpoints after the Item has been linked, based on the account type that was linked. Because virtually all Items that support Liabilities or Investments also support Transactions, this will maximize conversion. If you call an endpoint that is not applicable to the Item (for example, if you call [/liabilities/get](https://plaid.com/docs/api/products/liabilities/index.html.md#liabilitiesget) on a checking account, or [/investments/transactions/get](https://plaid.com/docs/api/products/investments/index.html.md#investmentstransactionsget) on a credit card account), the call will fail and you will not be billed for it. ##### Bank Income with Transactions  Initialize with Income Verification, add Transactions to Additional Consented Products, then call Transactions endpoints later, after the Item has been linked. Because Bank Income must fetch transaction data in order to verify the user's income, initializing with Transactions is not necessary. (Even though Bank Income uses transaction data, you will not be billed for Transactions on a Bank Income Item unless you add Transactions to the Item, either during or after Link.) ##### Bank Income with Assets  Initialize Link with both Income Verification and Assets in the Products array. Because institutions that support one of these products almost always support both of them, and because you will not be billed for Assets until you call the Assets endpoints, this is safe to do even if you aren't sure if you will use Assets. Assets can't be added to an Item post-Link without sending the user through Update Mode, so including Assets upfront will increase conversion. If you already have an Item enabled with one of these products and want to add the other: see the instructions on [Verifying Bank Income for existing Items](https://plaid.com/docs/income/bank-income/index.html.md#verifying-bank-income-for-existing-items) to add Bank Income to the Item. See the instructions on [Getting an Asset Report for an existing Item](https://plaid.com/docs/assets/index.html.md#getting-an-asset-report-for-an-existing-item) to add Assets. ##### Layer  For Layer, product initialization settings are configured in Layer templates via the Dashboard. Products set to **Always require** in the template impact Layer eligibility -- users will only be eligible for Layer if they have saved accounts at institutions that are compatible with these products. If a product is configured as **Require if supported**, **Optional**, **Additional consented**, or **Disabled**, users will still be eligible for Layer even if they do not have saved Items that are compatible with the product. If a user adds new accounts or institutions during Layer, the same restrictions impact which institutions and accounts they can add (e.g. if Auth is required, the user will only be able to add depository accounts that support ACH). ##### Layer with CRA and Transactions  If you are using Transactions in conjunction with both CRA products and Layer, then when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , provide `transactions` in the `additional_consented_products` array (rather than the `products` array) and call [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) only _after_ receiving the `USER_CHECK_REPORT_READY` webhook. This is necessary to avoid a known issue with Chase Bank Items in which CRA reports may fail to generate for Layer sessions if a Transactions extraction is triggered before the CRA report generation is complete. --- # Link - Institution status in Link | Plaid Docs Institution status in Link  =========================== #### Details of institution health status accessible in Link  #### Institution status in Link  Link proactively lets users know if an institution's connection isn't performing well. Below are the three views a user will see depending on the status of the institution they select. When the status of `item_logins` of an institution is `DEGRADED`, Link will warn users that they may experience issues and allow them to continue. Once the status of `item_logins` becomes `DOWN`, Link will block users from attempting to log in and suggest they find another bank. (An image of "Plaid Link institution status panels: Healthy allows credential input; Degraded shows connectivity issue; Down indicates connection failure.") Institution Health warnings can be tested in the Sandbox environment by using one of the dedicated ["Unhealthy" Platypus Bank test institutions](https://plaid.com/docs/sandbox/institutions/index.html.md#institution-details) . For a more detailed view of institution status, see the [status dashboard](https://dashboard.plaid.com/activity/status) , which provides a browsable view of institutions, supported products, and institution health. #### Connectivity not supported  (An image of "Plaid Link message: 'Connectivity not supported' for simple institution. Advises trying another institution.") If an institution is supported by Plaid, but is not supported by the product set or country codes Link was initialized with, a "Connectivity not supported" error message will appear. This message does not reflect the health of the institution. This message can be resolved by calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) with a more minimal product set, or by making sure you are Production-enabled for the country you are initializing Link for. For more details, see [Link troubleshooting](https://plaid.com/docs/link/troubleshooting/index.html.md#missing-institutions-or-connectivity-not-supported-error) . --- # Link - iOS | Plaid Docs Link iOS SDK  ============= #### Reference for integrating with the Link iOS SDK  #### Overview  The Plaid Link SDK is a quick and secure way to link bank accounts to Plaid from within your iOS app. LinkKit is a drop-in framework that handles connecting a financial institution to your app (credential validation, multi-factor authentication, error handling, etc.) without passing sensitive information to your server. [Prefer to learn by watching? Check out this quick guide to implementing Plaid on iOS devices](https://www.youtube.com/watch?v=QXHHRSSaspY) Want even more video lessons? A [full tutorial](https://youtu.be/9fgmW38usTo) for integrating Plaid with iOS is available on our YouTube channel. To get started with Plaid Link for iOS, clone the [GitHub repository](https://github.com/plaid/plaid-link-ios) and try out the example application, which provides a reference implementation in both Swift and Objective-C. Youʼll want to sign up for [free API keys](https://dashboard.plaid.com/developers/keys) through the Plaid Dashboard to get started. #### Initial iOS setup  Before writing code using the SDK, you must first perform some setup steps to register your app with Plaid and configure your project. The "Register your redirect URI" and "Set up Universal Links" steps describe setting up your app for OAuth redirects. If your integration uses only Link flows that do not initiate connections to financial institutions, such as the Identity Verification or Document Income flows, they can be skipped; they are mandatory otherwise. ##### Register your redirect URI  1. Sign in to the [Plaid Dashboard](https://dashboard.plaid.com/signin) and go to the [Team Settings -> API](https://dashboard.plaid.com/developers/api) page. 2. Next to **Allowed redirect URIs** click **Configure** then **Add New URI**. 3. Enter your redirect URI, which you must also set up as a Universal Link for your application, for example: `https://app.example.com/plaid/`. 4. Click **Save Changes**. These redirect URIs must be set up as [Universal Links](https://developer.apple.com/ios/universal-links/) in your application. For details, see Apple's documentation on [Allowing Apps and Websites to Link to Your Content](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) . Plaid does not support registering URLs with custom URL schemes as redirect URIs since they lack the security of Universal Links through the two-way association between your app and your website. Any application can register custom URL schemes and there is no further validation from iOS. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete Plaid OAuth flows, it is important that _your_ application is opened and not any arbitrary application that has registered the same URL scheme. ##### Set up Universal Links  In order for Plaid to return control back to your application after a user completes a bank's OAuth flow, you must specify a redirect URI, which will be the URI from which Link will be re-launched to complete the OAuth flow. The redirect URI must be a Universal Link. An example of a typical redirect URI is: `https://app.example.com/plaid`. Universal Links consist of the following parts: * An `applinks` entitlement for the Associated Domains capability in your app. For details, see Apple's documentation on the [Associated Domains Entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_associated-domains) and the [entitlements example](https://github.com/plaid/plaid-link-ios/blob/master/LinkDemo-Swift/LinkDemo-Swift/LinkDemo-Swift.entitlements) in the LinkDemo-Swift example app. * An `apple-app-site-association` file on your website. For details, see Apple's documentation on [Supporting Associated Domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains) and see our minimal example below. There are a few requirements for `apple-app-site-association` files: * Must be a static JSON file * Must be hosted using a `https://` scheme with a valid certificate and no redirects * Must be hosted at `https:///.well-known/apple-app-site-association` Below is an example for `https://my-app.com` (`https://my-app.com/.well-known/apple-app-site-association`) ```json { "applinks": { "details": [ { "appIDs": ["."], "components": [ { "/": "/plaid/*", "comment": "Matches any URL path whose path starts with /plaid/" } ] } ] } } ``` Once you have enabled Universal Links, your iOS app is now set up and ready to start integrating with the Plaid SDK. Ensure that the corresponding entry for the configured redirect URI in the `apple-app-site-association` file on your website continues to be available. If it is removed, OAuth sessions will fail until it is available again. #### Installation  Plaid Link for iOS is an embeddable framework that is bundled and distributed with your application. To obtain the necessary files and keep them up-to-date, we recommend using [Swift Package Manager](https://swiftpackageindex.com/plaid/plaid-link-ios) . Regardless of what you choose, submitting a new version of your application with the updated [LinkKit.xcframework](https://github.com/plaid/plaid-link-ios/releases) to the App Store is required. ##### Requirements  | LinkKit iOS version | Xcode toolchain minimum support | Supported iOS versions | | --- | --- | --- | | LinkKit 5.x.x | Xcode 15 | iOS 14 or greater | | LinkKit 4.x.x | Xcode 14 | iOS 11 or greater | | LinkKit 3.x.x | Xcode 13 | iOS 11 or greater | Select group for content switcher Swift Package ManagerCocoaPodsManual ##### Swift Package Manager  1. To integrate LinkKit using Swift Package Manager, Swift version >= 5.3 is required. 2. In your Xcode project from the Project Navigator (**Xcode ❯ View ❯ Navigators ❯ Project ⌘ 1**) select your project, activate the **Package Dependencies** tab and click on the plus symbol **➕** to open the **Add Package** popup window: (An image of "Xcode interface showing how to add a Swift package dependency; plus button highlighted.") 3. Enter the LinkKit package URL `https://github.com/plaid/plaid-link-ios-spm` into the search bar in the top right corner of the **Add Package** popup window. The main repository with full git history is very large (~1 GB), and Swift Package Manager always downloads the full repository with all git history. This `plaid-link-ios-spm` repository is much smaller (less than 500kb), making the download faster. 4. Select the `plaid-link-ios-spm` package. 5. Choose your **Dependency Rule** (we recommend **Up to Next Major Version**). 6. Select the project to which you would like to add LinkKit, then click **Add Package**: (An image of "Xcode screenshot showing input of Plaid Link iOS Swift package URL for package addition. 'Add Package' button highlighted.") 7. Select the `LinkKit` package product and click **Add Package**: (An image of "Dialog in Xcode for selecting Plaid link-ios package. 'LinkKit' checked, type 'Library', target 'MySampleApp'.") 8. Verify that the LinkKit Swift package was properly added as a package dependency to your project: (An image of "Xcode showing the Plaid Link iOS package dependency from GitHub in Package Dependencies tab.") 9. Select your application target and ensure that the LinkKit library is embedded into your application: (An image of "Xcode screenshot showing the Frameworks section with LinkKit listed under Package Dependencies for MySampleApp.") ##### CocoaPods  Using CocoaPods is highly discouraged. CocoaPods will officially become read-only on December 2, 2026. The last Plaid iOS SDK release that will support CocoaPods is 6.4.7 (released March 19, 2026). Version 7.x of the Plaid iOS SDK will not support CocoaPods. New integrations should use Swift Package Manager instead. 1. If you haven't already, install the latest version of [CocoaPods](https://guides.cocoapods.org/using/getting-started.html) . 2. If you don't have an existing Podfile, run the following command to create one: Create a new Podfile ```bash pod init ``` 3. Add this line to your `Podfile`: Edit the Podfile to include the following line ```bash pod 'Plaid' ``` 4. Run the following command: Install the Plaid and other CocoaPods ```bash pod install ``` 5. To update to newer releases in the future, run: Update the Plaid and other CocoaPods ```bash pod install ``` ##### Manual  Get the latest version of the [LinkKit.xcframework](https://github.com/plaid/plaid-link-ios/releases) and embed it into your application, for example by dragging and dropping the XCFramework bundle onto the **Embed Frameworks** build phase of your application target in Xcode as shown below. (An image of "Xcode project with LinkKit.xcframework added under Frameworks, Libraries, and Embedded Content. LinkKit.xcframework folder in Downloads.") ##### Camera Support (Identity Verification only)  When using the [Identity Verification](https://plaid.com/docs/identity-verification/index.html.md) product, the Link SDK may use the camera if a user needs to take a picture of identity documentation. To support this workflow, add a [NSCameraUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nscamerausagedescription) entry to your application's plist with an informative string. This allows iOS to prompt the user for camera access. iOS will crash your application if this string is not provided. ##### Upgrading  New versions of [LinkKit.xcframework](https://github.com/plaid/plaid-link-ios/releases) are released frequently. Major releases occur annually. The Link SDK uses Semantic Versioning, ensuring that all non-major releases are non-breaking, backwards-compatible updates. We recommend you update regularly (at least once a quarter, and ideally once a month) to ensure the best Plaid Link experience in your application. SDK versions are supported for two years; with each major SDK release, Plaid will stop officially supporting any previous SDK versions that are more than two years old. While these older versions are expected to continue to work without disruption, Plaid will not provide assistance with unsupported SDK versions. For details on each release see the [GitHub releases](https://github.com/plaid/plaid-link-ios/releases) and [version release notes](https://github.com/plaid/plaid-link-ios/blob/master/CHANGELOG.md) . #### Opening Link  Before you can open Link, you need to first create a `link_token`. A `link_token` can be configured for different Link flows and is used to control much of Link's behavior. To learn how to create a new `link_token`, see the API Reference entry for [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . For iOS the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) call must include the `redirect_uri` parameter and it must match the redirect URI you have configured with Plaid (see [Register your redirect URI](https://plaid.com/docs/link/ios/index.html.md#register-your-redirect-uri) above). ##### Create a Configuration  Starting the Plaid Link for iOS experience begins with creating a `link_token`. Once the `link_token` is passed to your app, create an instance of `LinkTokenConfiguration`, then create a `Handler` using `Plaid.create()` passing the previously created `LinkTokenConfiguration`. Plaid will begin to pre-load Link as soon as `Plaid.create()` is called, so to reduce UI latency when rendering Link, you should call `Plaid.create()` when initializing the screen where the user can enter the Link flow. After calling `Plaid.create()`, to show the Link UI, call `open()` on the handler passing your preferred presentation method. Note that each time you open Link, you will need to get a new `link_token` from your server and create a new `LinkTokenConfiguration` with it. **Properties** String Specify a `link_token` to authenticate your app with Link. This is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a `link_token` can be configured to launch Link in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . See the `/link/token/create` endpoint for more details. closure A required closure that is called when a user successfully links an Item. The closure should expect a single `LinkSuccess` argument, containing the `publicToken` String and a `metadata` of type `SuccessMetadata`. See [onSuccess](https://plaid.com#onsuccess) below. closure An optional closure that is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The closure should expect a single `LinkExit` argument, containing an optional `error` and a `metadata` of type `ExitMetadata`. See [onExit](https://plaid.com#onexit) below. closure An optional closure that is called when a user reaches certain points in the Link flow. The closure should expect a single `LinkEvent` argument, containing an `eventName` enum of type `EventType` and a `metadata` of type `EventMetadata`. See [onEvent](https://plaid.com#onevent) below. ```swift var linkConfiguration = LinkTokenConfiguration( token: "<#LINK_TOKEN_FROM_SERVER#>", onSuccess: { linkSuccess in // Send the linkSuccess.publicToken to your app server. } ) // Optional: Configure additional Link presentation options. // If true, skips the default Link loading animation. // Use this if you're displaying your own custom loading UI. linkConfiguration.noLoadingState = true // Optional: Configure additional Link presentation options - // Available in SDK v6.2.0 and above: // If false, displays a solid background instead of the default // transparent gradient. linkConfiguration.showGradientBackground = false ``` ```objectivec PLKLinkTokenConfiguration* linkConfiguration = [PLKLinkTokenConfiguration createWithToken:@"<#LINK_TOKEN_FROM_SERVER#>" onSuccess:^(PLKLinkSuccess *linkSuccess) { // Send the linkSuccess.publicToken to your app server. }]; // Optional: Configure additional Link presentation options: // If true, skips the default Link loading animation. // Use this if you're displaying your own custom loading UI. // Be sure to dismiss your loading UI when you receive the // OPEN and EXIT events. linkConfiguration.noLoadingState = YES; // Optional: Configure additional Link presentation options – // Available in SDK v6.2.0 and above: // If NO, displays a solid background instead of the default // transparent gradient. This is useful when customizing the UI or // providing your own background. For best results, also set // `noLoadingState = YES` to avoid conflicting visuals. linkConfiguration.showGradientBackground = NO; ``` ##### Create a Handler  A `Handler` is a one-time use object used to open a Link session. The `Handler` must be retained for the duration of the Plaid SDK flow. It will also be needed to respond to OAuth Universal Link redirects. For more details, see the [OAuth guide](https://plaid.com/docs/link/oauth/index.html.md#ios) . You can optionally provide an `onLoad` (available in **SDK v6.2.0 and above**) callback to know when Link has finished preloading and is ready to be presented. This is useful if you want to delay presenting Link until it's fully loaded, or enable related UI elements. Note for Layer customers: You should wait for the `LAYER_READY` event before presenting Link, rather than relying solely on `onLoad`. ```swift let result = Plaid.create(configuration, onLoad: { [weak self] in // Optional callback invoked once Plaid Link has finished preloading and is ready // to be presented. // // Example: Enable a button once Link has loaded // self?.openButton.isEnabled = true // // Example: Automatically present Link once it has loaded // guard let self = self else { return } // self.handler?.open(presentUsing: .viewController(self)) }) switch result { case .failure(let error): logger.error("Unable to create Plaid handler due to: \(error)") case .success(let handler): // Retain the handler for the duration of the Link flow (and OAuth redirects) self.handler = handler } ``` ```objectivec // Choose ONE of the following examples. In both cases, retain the handler for the // duration of the Link flow (and OAuth redirects). // --- Example 1: With onLoad (requires iOS SDK v6.2.0+) --- { NSError *createError = nil; id handler = [PLKPlaid createWithLinkTokenConfiguration:linkConfiguration onLoad:^{ // Optional callback that is invoked once Plaid Link has // finished loading and is ready to be presented. // You could use your own loading UI and automatically launch // Link when this callback fires. // // Example: // [self.linkHandler openWithPresentUsing:[PLKPresentationMethod viewController:self]]; // // Example: Enable a button once Link has loaded // self.openButton.enabled = YES; } error:&createError]; if (handler) { self.linkHandler = handler; } else { NSLog(@"Unable to create PLKHandler due to: %@", createError); } } // --- Example 2: Without onLoad --- { NSError *createError = nil; id handler = [PLKPlaid createWithLinkTokenConfiguration:linkConfiguration error:&createError]; if (handler) { self.linkHandler = handler; } else { NSLog(@"Unable to create PLKHandler due to: %@", createError); } } ``` ##### Open Link  Finally, open Link by calling `open` on the `Handler` object. This will usually be done in a button's target action. ```swift let method: PresentationMethod = .viewController(self) handler.open(presentUsing: method) ``` ```objectivec [handler openWithContextViewController:self]; ``` \=\*=\*=\*= #### onSuccess  The closure is called when a user successfully links an Item. It should take a single `LinkSuccess` argument, containing the `publicToken` String and a `metadata` of type `SuccessMetadata`. **Properties** LinkSuccess Contains the `publicToken` and `metadata` for this successful flow. String Displayed once a user has successfully completed Link. If using Identity Verification or Beacon, this field will be `null`. If using Document Income or Payroll Income, the `public_token` will be returned, but is not used. LinkSuccess Displayed once a user has successfully completed Link. nullable, Institution An institution object. If the Item was created via Same-Day micro-deposit verification, will be `null`. String The full institution name, such as 'Wells Fargo' InstitutionID (String) The Plaid institution identifier Array A list of accounts attached to the connected Item AccountID (String) The Plaid `account_id` String The official account name Optional (Optional) The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user. AccountSubtype The account subtype and its type. See [Account Types](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values. Optional Indicates an Item's micro-deposit-based verification or database verification status. Possible values are: `pending_automatic_verification`: The Item is pending automatic verification. `pending_manual_verification`: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the deposit. `automatically_verified`: The Item has successfully been automatically verified. `manually_verified`: The Item has successfully been manually verified. `verification_expired`: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. `verification_failed`: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. `database_matched`: The Item has successfully been verified using Plaid's data sources. `database_insights_pending`: The Database Insights result is pending and will be available upon Auth request. `nil`: Neither micro-deposit-based verification nor database verification are being used for the Item. String A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround. String Unprocessed metadata, formatted as JSON, sent from the Plaid API. ```swift onSuccess: { linkSuccess in // Send the linkSuccess.publicToken to your app server. } ``` ```objectivec onSuccess:^(PLKLinkSuccess *success) { // Send the linkSuccess.publicToken to your app server. } ``` \=\*=\*=\*= #### onExit  This optional closure is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. It should take a single `LinkExit` argument, containing an optional `error` and a `metadata` of type `ExitMetadata`. **Properties** LinkExit Contains the optional `error` and `metadata` for when the flow was exited. Optional (Swift), Optional (Objective-C) An Error type that contains the `errorCode`, `errorMessage`, and `displayMessage` of the error that was last encountered by the user. If no error was encountered, `error` will be `nil`. In Objective-C, field names will match the `NSError` type. ExitErrorCode The error code and error type that the user encountered. Each `errorCode` has an associated `errorType`, which is a broad categorization of the error. String A developer-friendly representation of the error code. Optional A user-friendly representation of the error code or `nil` if the error is not related to user action. This may change over time and is not safe for programmatic use. ExitMetadata Displayed if a user exits Link without successfully linking an Item. Optional The status key