Plaid periodically migrates institutions to new platforms. Common causes include a move to an OAuth API, a platform change by the bank, or a bank merger or acquisition.
In general, you do not need to do anything in response to an institution migration. However, migrations may result in spikes in the number of broken Items at an institution or changes to institution data returned by Plaid, so understanding what is happening can help you operationally manage your Plaid integration.
Ensuring that you have properly built your Plaid integration to handle errors and webhooks will result in lower error rates and improved robustness to migrations.
What happens to existing Items in a migration?
Exactly what happens during a migration will vary depending on the exact cause of the migration and how the institution has chosen to implement the change. Details of what will happen, if available, will be found on the institution page on the Dashboard.
In many cases, the migration will be seamless: Plaid moves existing Items to the new integration in the background, with no Item breakage and no action required from you or your users.
In other cases, during a migration, impacted Items may enter an ITEM_LOGIN_REQUIRED error state, which can be resolved through update mode as normal. To proactively avoid Item breakages, you can listen for the PENDING_DISCONNECT webhook and send the Item through update mode in response. Note that not all migrations will send this webhook.
Sometimes, especially in the case of a bank acquisition, the Item may be permanently broken and cannot be fixed by update mode. If this is the case, update mode will fail with the error INSTITUTION_NO_LONGER_SUPPORTED, or the user will encounter an institution-provided error within the institution's own OAuth login flow.
What happens to institution IDs in a migration?
In most cases, the institution_id will not change. However, the same institution can sometimes have multiple records with different institution_ids — for example, separate OAuth and non-OAuth versions, or separate login portals. When a migration introduces a new ID, Plaid will communicate the old → new mapping in the Dashboard notice.
In the case of a bank acquisition, Items at the acquired institution usually migrate to the acquiring institution's institution_id, and the acquired institution's ID is eventually retired. Unlike institution_ids, item_ids are immutable: an Item's item_id will not change as the result of a migration.
How do I learn about planned or ongoing migrations?
Institutions that are currently migrating, have recently migrated, or are scheduled to migrate are listed on the Migrations tab in the Dashboard. Click through to the institution for more details about the migration.
For especially large migrations, Plaid may proactively reach out to impacted customers.
Note that migrations happen as institutions modernize or consolidate and do not occur on a fixed schedule. Plaid will provide as much advance notice as possible regarding migrations. To keep up to date, monitor the Migrations tab regularly.
How can I ensure my integration is robust to migrations?
- Handle the
PENDING_DISCONNECTwebhook and theITEM_LOGIN_REQUIREDerror state, and prompt the user to enter update mode. - If you see a spike in errors for Items at a specific institution, check the institution's page in the Dashboard for information about possible migrations before filing a support ticket.
- If your UI shows institution-specific details (like displaying a bank logo or name next to a customer's connected account), make sure to update these after a migration by calling
/item/getor/institutions/get_by_id. - Avoid building critical logic hard coded to an
institution_id, as these can change after a migration.