Plaid logo
Docs
ALL DOCS

Link

  • Overview
Libraries
  • Web
  • iOS
  • Android
  • React Native
  • Webview
Core Link flows
  • OAuth guide
  • Update mode
  • Preventing duplicate Items
  • Data Transparency Messaging migration
  • Account Select v2 migration guide
  • Link Token migration guide
  • Legacy public key integrations
Optimizing Link
  • Optimizing Link conversion
  • Measuring Link conversion
  • Pre-Link messaging
  • Customizing Link
  • Choosing when to inititalize products
  • Returning user experience
  • 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
Open nav

Link overview

Use Link to connect to your users' financial accounts with the Plaid API

image of Plaid Link UI

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.

Plaid Link will handle credential validation, multi-factor authentication, and error handling for each institution that we support. Link works across all modern browsers and platforms, including web, iOS, Android, as well as via React Native and mobile webviews, along with community-supported wrappers for Flutter and Expo.

To try Link, see Plaid Link Demo.

Want to build a Plaid-powered application using Link directly in your browser? The Plaid Basics interactive tutorial can walk you through the process.

Link flow overview

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.

The Plaid flow begins when your user wants to connect their bank account to your app.
Step  diagram
1Call /link/token/create to create a link_token and pass the temporary token to your app's client.
Step 1 diagram
2Use the link_token to open Link for your user. In the onSuccess callback, Link will provide a temporary public_token.
Step 2 diagram
3Call /item/public_token/exchange to exchange the public_token for a permanent access_token and item_id for the new Item.
Step 3 diagram
4Store the access_token and use it to make product requests for your user's Item.
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 callback containing a public_token, which can be exchanged for an access_token via /item/public_token/exchange.

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, iOS, Android, React Native or mobile webview.

Supporting OAuth

Some 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 how to connect to an institution that uses OAuth, see the OAuth guide.

Plaid now requires that all developers (except those using only Identity Verification, Monitor, or Wallet Onboard) integrate OAuth support into their apps. Without OAuth support, your application will be unable to connect to some of the top 10 largest financial institutions in the US, or to most institutions in Europe.

Customizing Link

You can customize parts of Link's flow, including some text elements, the institution select view, and the background color, and enable additional features like the Account Select view straight from the Dashboard. You can preview your changes in realtime and then publish them instantly once you're ready to go live. For more details, see Link customization.

To help you take advantage of the options available for customizing and configuring Link, Plaid offers a best practices guide with recommendations for how to initialize and configure Link within your app.

Link's appearance will also automatically change if the institution selected is not in a healthy state. For more details, see Institution status in Link.

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.

Error-handling flows

If your application will access an Item on a recurring basis, rather than just once, it should support update mode. 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.

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.

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.

Optimizing Link conversion

How you configure Link can have a huge impact on the percentage of users who successfully complete the Link flow. To ensure you're maximizing conversion, see Best practices for Link conversion.

Link token migration

Prior to July 2020, Link was initialized using a public key instead of a link_token. If you are an existing Plaid developer using a Plaid public key, it is recommended that you migrate to a link_token-based implementation as soon as possible, using the instructions in the Link token migration guide. For those who are not yet ready to migrate, instructions on maintaining a legacy integration can be found in the legacy integration guide.

Account Select v2 migration

In September 2021, Plaid introduced an update to the Account Select pane (Account Select v2). When using Account Select v2, if a user links an Item at an institution where they hold multiple accounts, you will only receive data from the specific account(s) the user has selected to share with you. Migration to Account Select v2 is required; any Plaid integrations still using Account Select v1 will be automatically migrated beginning in March 2022. To learn more, see the Account Select v2 migration guide.

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 section.

Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord