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.
1OPEN2TRANSITION_VIEW3SELECT_INSTITUTION4TRANSITION_VIEW5SUBMIT_CREDENTIALS6TRANSITION_VIEW7HANDOFF
1OPEN2TRANSITION_VIEW3SELECT_INSTITUTION4TRANSITION_VIEW5SUBMIT_CREDENTIALS6TRANSITION_VIEW7ERROR8TRANSITION_VIEW9SUBMIT_CREDENTIALS10TRANSITION_VIEW11ERROR12TRANSITION_VIEW13EXIT
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
.
1OPEN (view_name = CONSENT)2TRANSITION_VIEW (view_name = SELECT_INSTITUTION)3SELECT_INSTITUTION4TRANSITION_VIEW (view_name = OAUTH)5OPEN_OAUTH6...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:
1OPEN2TRANSITION_VIEW (view_name = SELECT_INSTITUTION)3SELECT_INSTITUTION (view_name = OAUTH <or> CREDENTIAL)4SUBMIT_CREDENTIALS <or> OPEN_OAUTH5TRANSITION_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.
1...2SELECT_INSTITUTION3TRANSITION_VIEW (view_name = OAUTH)4OPEN_OAUTH5TRANSITION_VIEW (view_name = CONNECTED)6HANDOFF
1...2SELECT_INSTITUTION3TRANSITION_VIEW (view_name = CREDENTIAL)4SUBMIT_CREDENTIALS5TRANSITION_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.
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
Supporting OAuth
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/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 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.
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.
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).
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).
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.