Link best practices

Discover recommendations for improving Link conversion, avoiding common Link configuration errors, and more

Prefer to learn by watching? A video guide is available for this topic.

This guide contains tips for optimizing your existing Link implementation to help increase conversion, improve your users’ experiences with Link, and avoid common mistakes and misconfiguration errors. If you are new to Link or don’t yet have a working Link integration, see Link overview for instructions on getting started with Link.

Improving Link conversion

Successful Link attempts will result in an onSuccess callback; unsuccessful attempts will result in an onExit callback. By tracking the counts of these callbacks, you can measure both successful and unsuccessful attempts to link accounts. In addition, you can obtain insight into at what point a user abandoned Link by tracking the metadata.status field within onExit or viewing the events emitted by Link through the onEvent callback.

Example series of events from a successful Link attempt
1OPEN
2TRANSITION_VIEW
3SELECT_INSTITUTION
4TRANSITION_VIEW
5SUBMIT_CREDENTIALS
6TRANSITION_VIEW
7HANDOFF

Events from an unsuccessful Link attempt, wrong password entered repeatedly
1OPEN
2TRANSITION_VIEW
3SELECT_INSTITUTION
4TRANSITION_VIEW
5SUBMIT_CREDENTIALS
6TRANSITION_VIEW
7ERROR
8TRANSITION_VIEW
9SUBMIT_CREDENTIALS
10TRANSITION_VIEW
11ERROR
12TRANSITION_VIEW
13EXIT

Beginning July 2022, Link will no longer issue the SUBMIT_CREDENTIALS event when a user authenticates with an institution that requires OAuth. Link issues the OPEN_OAUTH event when a user chooses to be redirected to the institution’s OAuth portal. It is recommended to track this event instead of SUBMIT_CREDENTIALS.

Example series of events from a user who connects an institution supported by OAuth
1OPEN (view_name = CONSENT)
2TRANSITION_VIEW (view_name = SELECT_INSTITUTION)
3SELECT_INSTITUTION
4TRANSITION_VIEW (view_name = OAUTH)
5OPEN_OAUTH
6...
7(The user completes the OAuth flow at their bank)
8...
9TRANSITION_VIEW (view_name = CONNECTED)
10HANDOFF

Though users can go through multiple authentication flow types, you can track user conversion in one funnel by joining the OPEN_OAUTH or SUBMIT_CREDENTIALS events:

Single funnel to estimate conversion
1OPEN 
2TRANSITION_VIEW (view_name = SELECT_INSTITUTION) 
3SELECT_INSTITUTION (view_name = OAUTH <or> CREDENTIAL)
4SUBMIT_CREDENTIALS <or> OPEN_OAUTH 
5TRANSITION_VIEW (view_name = CONNECTED)
6HANDOFF

To measure conversion through the OAuth and credentials-based flows separately, filter institutions based on the TRANSITION_VIEW event after the SELECT_INSTITUTION event.

Key funnel steps for OAuth institutions
1...
2SELECT_INSTITUTION
3TRANSITION_VIEW (view_name = OAUTH)
4OPEN_OAUTH
5TRANSITION_VIEW (view_name = CONNECTED)
6HANDOFF

Key funnel steps for credentials-based institutions
1...
2SELECT_INSTITUTION
3TRANSITION_VIEW (view_name = CREDENTIAL)
4SUBMIT_CREDENTIALS
5TRANSITION_VIEW (view_name = MFA, mfa_type = code)
6SUBMIT_MFA (mfa_type = code)
7TRANSITION_VIEW (view_name = CONNECTED)
8HANDOFF

You can also capture the institution_name field, provided by the onEvent callback, to track which institutions your users most commonly attempt to link. If users frequently attempt to link institutions that require OAuth support, such as Capital One, you may want to prioritize adding OAuth support; if they attempt to link smaller banks and you are using Auth, you may want to support alternative Auth methods.

A more complete list of steps you can take that may help increase successful Link attempts can be found below.

Customizing Link

Plaid enables you to customize certain visual aspects of your app’s interactions with Link via the customization pane in the dashboard.

Select the “co-branded” option for the Consent customization to upload a brand logo and highlight the shared trust between your app and Plaid.

Customize the title of the consent screen to best align with how your customers refer to their information being shared. For example, “[App name] uses Plaid to connect your [custom field]”.

Tweak the customizations offered around text strings, buttons, and colors to match your brand.

Create customized profiles corresponding to language and country settings to display Link to your users in a way that matches their preferred internationalization settings in your app.

For more details on all of the aspects of Link you can customize, and how to do so, see Link Customization.

Providing pre-Link messaging

Set user expectations about the Link experience before launching Link. Explain why you are prompting them to link their account and the benefits of completing the Link flow. Tell the user what the next steps within the flow will be: for example, let them know beforehand that they’ll be asked to log into their financial institution account.

Using the Returning User Experience

If your application’s onboarding flow verifies the user’s phone number before they enter Plaid Link, you may be able to take advantage of the returning user experience (RUX), which allows users to authenticate using a streamlined flow with less data entry. For more information, see Returning User Experience.

Prompting users to remediate ITEM_LOGIN_REQUIRED errors

When a user changes their credentials, MFA, or security settings, or when a bank makes changes to its infrastructure, Plaid’s connection to the user’s bank account may be disconnected. This results in an ITEM_LOGIN_REQUIRED error. When an Item enters this state, the user’s data is no longer retrievable. To be alerted when Items enter bad states, listen for Item webhooks. To resolve the ITEM_LOGIN_REQUIRED error, you will need to prompt the user to re-authenticate using Link’s update mode.

To encourage users to re-authenticate, you can:

Notify users in-app or via email if they have Items in an error state. Alert them that there’s a problem with the connection to their financial institution account, which they can resolve by re-authenticating.

Message users about why it’s important to re-link their account(s) and ask them to do so by taking them directly to the screen with Link’s update mode.

(Auth only) Supporting Instant Match or micro-deposits

Implement support for Instant Match and micro-deposit-based authentication. Supporting these authentication methods enables Auth access for users at thousands of smaller banks and credit unions across the US.

Supporting OAuth

OAuth support is required for users to link accounts at certain large financial institutions, including Capital One. For more information, see the OAuth guide.

Initializing Link only for required products

Make sure to include only products you need in the /link/token/create products array. Otherwise, you may reduce conversion by preventing some institutions from appearing in Link. For more details, see Choosing when to initialize products.

Other usability recommendations

Implementing error handling for onExit

The onExit callback is called when a user exits Link without successfully linking their account; appropriately handling this callback and connecting it to a logical flow can improve user experience. For example, if an onExit callback contains a metadata status of institution_not_found, consider automatically navigating the user to a backup flow (e.g. micro-deposits for an Auth use case).

De-duping duplicate Items

To avoid user confusion and avoid double-billing, implement logic to prevent users from Linking the same Item twice.

Specifying a webhook handler

A webhook destination URL can be configured at the point of creating your Link Token. Webhooks are a core part of Plaid's API, and most applications that integrate with Plaid should be configured to listen to Plaid webhooks. To learn more, see Webhooks.

Choosing when to initialize products

The products you choose to configure Link with can have implications for billing, the Institution Select Pane, and product performance. While Link must be initialized with at least one product, you can often choose whether initialize Link with a product or to instead initialize the Item with that product post-Link.

If an Item was not initialized with a given product at the time of Link, making a product endpoint call for information about that Item will automatically initialize the Item. For example, if an Item was not initialized with Transactions during Link, calling /transactions/sync or /transactions/get on that Item for the first time will initialize it with the Transactions product.

There are some exceptions to this flexibility:

To use Instant Match, Automated Micro-deposits, or Same Day Micro-deposits, Auth cannot be initialized post-Link.
To use Same Day Micro-deposits, Auth must be the only product Link is initialized with.
To use Document Income or Payroll Income, Income Verification must be the only product Link is initialized with.
Assets, Income, and Payment Initiation cannot be initialized post-Link.
If using the pre-authenticated Returning User Experience, you cannot initialize any products post-Link.

Impacts on billing

If you initialize Link with a product that is billed under an initialization or subscription model, you will be billed when an Item for the product is created, even if you are not yet using the product’s endpoints.

To avoid unwanted charges, do not initialize Link with a product in Production unless you are sure you are going to use that product.

To learn more about how Plaid bills each product, see Billing.

Impacts on accounts and institutions in Link

Plaid filters the institution list displayed to the user based on the products Link is initialized with. If Link is initialized with multiple products, only institutions supporting all of those products will be available.

On the account select screen, Plaid filters the account list displayed to the user based on the products Link is initialized with. Only accounts compatible with all products will be available.

To avoid overly filtering the institution or account list, initialize Link with your required products and call other products’ endpoints later.

Impacts on performance

Plaid begins to prepare transactions data upon Item link if Link is initialized with transactions, or upon the first call to either /transactions/sync or /transactions/get. Similarly, Plaid begins to prepare investments transactions data upon Item link if Link is initialized with investments, or upon the first call to /investments/transactions/get otherwise.

Preparing transactions data can take up to several minutes depending on the amount of history available, so you may be able to retrieve transactions more quickly by initializing Link with Transactions and/or Investments.

Choosing when to enable Account Select and account filtering

Account Select

Account Select, if enabled, creates a pane that allows users to select one or more of the account(s) at their institution. If using Account Select, the Connected pane will be skipped and the onSuccess callback will fire after the user selects their account(s).

Enable Account Select if you believe users may only want your application to interact with a subset of their accounts at a specific institution, or if your application expects only one account to be used with it.

For example, if you anticipate a use case where users want to move money with Auth -- and know which specific account(s) they need to have money coming from and going to -- enable Account Select.

For more information on Account Select, see Link Customization.

Account filtering

Account type/subtype filtering lets you configure the Link flow to show only the institutions that support the account types and subtypes relevant to your use case. Account filtering can be enabled when calling /link/token/create and applies to both the Institution Select pane and the Account Select pane (if enabled).

If your app should only work with certain account subtypes, enable account subtype filtering.

As an example, say your app can perform frequent funds transfers out of the linked account, but savings accounts in the US are limited to six outgoing transfers per month. In this case, you may want to apply a checking account subtype filter in conjunction with enabling Account Select. Then, the user will only see checking accounts on the Account Select pane. For more information, see Account subtype filters.