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
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.
Plaid enables you to customize certain visual aspects of your app’s interactions with Link via the customization pane in the dashboard.
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
Using the 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:
(Auth only) Supporting Instant Match or micro-deposits
Initializing Link only for required products
Other usability recommendations
Implementing error handling for onExit
De-duping duplicate Items
Specifying a webhook handler
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/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 Income, Income 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 learn more about how Plaid bills each product, see Billing.
Impacts on institution select
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.
Impacts on performance
Plaid begins to prepare transactions data upon Item link if Link is initialized with
transactions, or upon the first call to
/transactions/get otherwise. Similarly, Plaid begins to prepare investments transactions data upon Item link if Link is initialized with
investments, or upon the first call to
Choosing when to enable Account Select and account filtering
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).
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 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).
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.