Plaid logo
Docs
ALL DOCS

Link

  • Overview
Libraries
  • Web
  • iOS
  • Android
  • React Native
  • Webview
Core Link flows
  • Link Token migration guide
  • OAuth guide
  • Account Select v2 migration guide
  • Update mode
  • Legacy public key integrations
Optimize Link
  • Customizing Link
  • Duplicate Items
  • Returning user experience
  • Link best practices
  • Modular Link (UK/EU only)
Errors and troubleshooting
  • Troubleshooting
  • Handling an invalid Link Token
  • Institution status in Link
Plaid logo
Docs
Plaid.com
Get API keys

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.

1OPEN
2TRANSITION_VIEW
3SELECT_INSTITUTION
4TRANSITION_VIEW
5SUBMIT_CREDENTIALS
6TRANSITION_VIEW
7HANDOFF
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.

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:

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.

1...
2SELECT_INSTITUTION
3TRANSITION_VIEW (view_name = OAUTH)
4OPEN_OAUTH
5TRANSITION_VIEW (view_name = CONNECTED)
6HANDOFF
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.

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.

Was this helpful?
Developer community
Github logo
StackOverflow logo
Twitter logo