Updating Items via Link
Use update mode to add permissions to Items, or to resolve ITEM_LOGIN_REQUIRED or PAYMENT_PROFILE_LOGIN_REQUIRED statuses

When to use update mode
Update mode is used to update authentication or authorization for an Item. The most common reason for this is when access to an existing Item stops working: 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 with update mode 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. Update Mode can also be used to request permission to access data that the user did not originally grant during the initial link flow. This can include specific OAuth permissions, or access to new accounts or additional product scopes.
Resolving ITEM_LOGIN_REQUIRED or PENDING_EXPIRATION errors
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.
Resolving PAYMENT_PROFILE_LOGIN_REQUIRED authorization decision rationale
Receiving the PAYMENT_PROFILE_LOGIN_REQUIRED
authorization decision rationale from the /transfer/authorization/create
response indicates that the bank login for this Payment Profile has expired.
Ask the user to re-authenticate with Link in Payment Profile update mode, which will prompt the user to re-login and return the Payment Profile into a good state for subsequent transfers.
Requesting additional permissions
Update mode can also be used to collect additional permissions.
If using Account Select v2, you can 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.
If using Data Transparency Messaging, update mode can be used to request permissions for additional product scopes.
Triggering update mode for an OAuth institution will cause the user to re-enter the OAuth flow. They can then grant any required OAuth permissions they failed to grant originally, or restore OAuth permissions they may have revoked.
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 switcher1// Create a one-time use link_token for the Item.2// This link_token can be used to initialize Link3// in update mode for the user4const 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);1617 // Use the link_token to initialize Link18 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.
1// Initialize Link with the token parameter2// set to the generated link_token for the Item3const linkHandler = Plaid.create({4 token: 'GENERATED_LINK_TOKEN',5 onSuccess: (public_token, metadata) => {6 // You do not need to repeat the /item/public_token/exchange7 // 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 prior14 // to exiting.15 }16 // metadata contains the most recent API request ID and the17 // Link session ID. Storing this information is helpful18 // 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:
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.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.(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 theaccounts
field in theonSuccess()
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.
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}'
Note that when using the Assets product specifically, if a user selects additional accounts during update mode but does not successfully complete the Link flow, assets authorization will be revoked from the Item. If this occurs, have the user go through a new Link flow in order to generate an Asset Report, or, if you have Data Transparency Messaging enabled, use update mode to re-authorize the Item for assets, as described in the next section.
Using update mode to request additional consent for products
If you have Data Transparency Messaging enabled, you need user consent to access new products. 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:
- The
additional_consented_products
field should be set to include any new products you want to gather consent for.- For example, if Link was initialized with just Transactions and you want to upgrade to Identity, you would pass in
identity
to theadditional_consented_products
field. - To see the currently authorized and consented products on an Item, use the
/item/get
endpoint
- For example, if Link was initialized with just Transactions and you want to upgrade to Identity, you would pass in
- The
link_customization_name
should be set to a customization with Data Transparency Messaging enabled. The use case string should also be broadened to include your reasons for accessing the new data. If the use case is not customized, the default use case will be present on the Data Transparency Messaging pane.
If the upgrade was successful, you will receive the onSuccess()
callback and you will have access to the API endpoints for all of the products you passed into Link update mode. The new products will only be billed once the related API endpoints are called, even if they would otherwise be billed upon Item initialization (e.g., Transactions).
Using update mode for Payment Profiles
To use update mode for Transfer's Payment Profile, initialize Link by creating a link_token
using the /link/token/create
endpoint with transfer.payment_profile_token
configured for the Payment Profile you intend to update.
In addition, make sure you specify the following:
- The
products
field should not be supplied. - The
user
object should have no phone number field supplied.
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 "transfer": { "payment_profile_token": "PAYMENT_PROFILE_TOKEN" }11}'
Payment Profile update mode will prompt the user to log in to their financial institution in order to re-authenticate their previously linked account. If the user does not complete the Payment Profile update mode flow, you will have to create a new Payment Profile for the user.
After the user successfully logs back in, you can call /transfer/authorization/create
to determine transfer failure risk.
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.
Testing Payment Profile update mode
Transfer specific Payment Profile update mode can be tested in Sandbox using the /sandbox/payment_profile/reset_login
endpoint, which will force a Payment Profile into a state where the login is no longer valid. Subsequent calls with the Payment Profile to /transfer/authorization/create
will result in the PAYMENT_PROFILE_LOGIN_REQUIRED
decision rationale getting returned.
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 and rationale
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
– This error suggest the financial institution indicated that the user's password or MFA information has changed. They will need to reauthenticate via Link's update mode.INVALID_UPDATED_USERNAME
– This error indicates the username associated with an item is no longer valid.PAYMENT_PROFILE_LOGIN_REQUIRED
- This rationale indicates that the financial institution login for the Payment Profile is expired.
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.