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
Open nav

Updating Items via Link

Use Link's update mode to fix Items that require re-authentication and resolve the ITEM_LOGIN_REQUIRED error code

image of Plaid Link update mode flow

When to use update mode

Over time, an Item may need to refresh its authentication information. This can happen if the end user changes a password, if multi-factor authentication (MFA) requirements change, or if the login becomes locked. An Item can also require its authentication to be refreshed if it was only authorized for a limited amount of time and the authorization has expired or is nearing expiration, which can happen to Items from institutions that use OAuth flows in Plaid Link.

Receiving an ITEM_LOGIN_REQUIRED error or a PENDING_EXPIRATION webhook indicates that the Item should be re-initialized via update mode.

If you receive the ITEM_LOGIN_REQUIRED error after calling a Plaid endpoint, implement Link in update mode during the user flow, and ask the user to re-authenticate before proceeding to the next step in your flow.

If you receive the ITEM_LOGIN_REQUIRED error via the ITEM: ERROR webhook, or if you receive the PENDING_EXPIRATION webhook, re-authenticate with Link in update mode when the user is next in your app. You will need to tell your user (using in-app messaging and/or notifications such as email or text message) to return to your app to fix their Item.

If using Account Select v2, you can also use update mode to request your users to share new accounts with you. Receiving a NEW_ACCOUNTS_AVAILABLE webhook indicates that Plaid has detected new accounts that you may want to ask your users to share.

Using update mode

To use update mode for an Item, initialize Link with a link_token configured with the access_token for the Item that you wish to update. Note that no products should be specified when creating a link_token for update mode. You can obtain a link_token using the /link/token/create endpoint.

If you're using update mode to refresh an OAuth institution, ensure you configure the Link token with a redirect URI, as described in Configure your Link token with your redirect URI.

Select group for content switcher
Select Language
Copy
1// Create a one-time use link_token for the Item.
2// This link_token can be used to initialize Link
3// in update mode for the user
4const configs = {
5 user: {
6 client_user_id: 'UNIQUE_USER_ID',
7 },
8 client_name: 'Your App Name Here',
9 country_codes: [CountryCode.Us],
10 language: 'en',
11 webhook: 'https://webhook.sample.com',
12 access_token: 'ENTER_YOUR_ACCESS_TOKEN_HERE',
13};
14app.post('/create_link_token', async (request, response, next) => {
15 const linkTokenResponse = await client.linkTokenCreate(configs);
16
17 // Use the link_token to initialize Link
18 response.json({ link_token: linkTokenResponse.data.link_token });
19});

Link auto-detects the appropriate institution and handles the credential and multi-factor authentication process, if needed.

An Item's access_token does not change when using Link in update mode, so there is no need to repeat the exchange token process.

Copy
1// Initialize Link with the token parameter
2// set to the generated link_token for the Item
3const linkHandler = Plaid.create({
4 token: 'GENERATED_LINK_TOKEN',
5 onSuccess: (public_token, metadata) => {
6 // You do not need to repeat the /item/public_token/exchange
7 // process when a user uses Link in update mode.
8 // The Item's access_token has not changed.
9 },
10 onExit: (err, metadata) => {
11 // The user exited the Link flow.
12 if (err != null) {
13 // The user encountered a Plaid API error prior
14 // to exiting.
15 }
16 // metadata contains the most recent API request ID and the
17 // Link session ID. Storing this information is helpful
18 // for support.
19 },
20});

Link will automatically detect the institution ID associated with the link_token and present the appropriate credential view to your user.

If your integration is still using a public_token to open Link in update mode, see the migration guide to upgrade to link_tokens. You can also see the maintenance guide to troubleshoot any public_token issues.

When an Item is restored from the ITEM_LOGIN_REQUIRED state via update mode, if it has been initialized with a product that sends Item webhooks (such as Transactions or Investments), the next webhook fired for the Item will include data for all missed information back to the last time Plaid made a successful connection to the Item.

Using update mode to request new accounts

You can allow end users to add new accounts to an Item by enabling Account Select when initializing Link in update mode. To do so, first initialize Link for update mode by creating a link_token using the /link/token/create endpoint. For OAuth institutions, ensure you configure the Link token with a redirect URI, as described in Configure your Link token with your redirect URI.

In addition, make sure you specify the following:

  1. The update.account_selection_enabled flag set to true. To ensure you are able to use this flag, check that your Plaid library meets the minimum version required.

  2. A link_customization_name for a customization that enables Account Select v2. The settings on this customization will determine which View Behavior for the Account Select pane is shown in update flow.

  3. (Optional) Any account_filters to specify account filtering. Note that this field cannot be set for update mode if account selection isn’t enabled. Once your user has updated their account selection, all selected accounts will be shared in the accounts field in the onSuccess() callback from Link. Any de-selected accounts will no longer be shared with you. You will only be able to receive data for these accounts the user selects in update mode going forward.

We recommend that you remove any data associated with accounts that your user has de-selected.

Select Language
Copy
1curl -X POST https://sandbox.plaid.com/link/token/create \
2-H 'Content-Type: application/json' \
3-d '{
4 "client_id": "CLIENT_ID",
5 "secret": "SECRET",
6 "client_name": "My App",
7 "user": { "client_user_id": "UNIQUE_USER_ID" },
8 "country_codes": ["US"],
9 "language": "en",
10 "webhook": "https://webhook.sample.com",
11 "access_token": "ENTER_YOUR_ACCESS_TOKEN",
12 "link_customization_name": "account_selection_v2_customization",
13 "update": { "account_selection_enabled": true }
14}'

Updating account selections for Items with the Assets product is not supported, as Plaid needs to receive end user consent on the updated account selection. To add accounts when using Assets, create a new Item, which will give end users the ability to review the data before sharing the data with your app.

Testing update mode

Update mode can be tested in the Sandbox using the /sandbox/item/reset_login endpoint, which will force a given Item into an ITEM_LOGIN_REQUIRED state.

Example React code in Plaid Pattern

For a real-life example that illustrates the handling of update mode, see linkTokens.js and LaunchLink.tsx. These files contain the Link update mode code for the React-based Plaid Pattern sample app.

Related errors

Below is a list of errors that you may encounter in update mode or that may cause you to launch the update mode flow:

  • ITEM_LOGIN_REQUIRED – The financial institution indicated that the user's password or MFA information has changed. They will need to reauthenticate via Link's update mode.
  • ITEM_NO_ERROR – Link was initialized in update mode for an Item that is in a good state. No further action is required.
  • INVALID_UPDATED_USERNAME – The username associated with an item is no longer valid.

Account selection screens in update mode

To demonstrate the user experience of various update mode flows, below are screenshots of update mode that correspond to different Account Select V2 settings.

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