Plaid logo
Docs
ALL DOCS

Link

  • Overview
Platforms
  • Web
  • iOS
  • Android
  • React Native
  • Hosted Link
Core Link functionality
  • OAuth guide
  • Update mode
  • Preventing duplicate Items
  • Data Transparency Messaging migration
  • Returning user experience
Additional Link modes
  • Embedded Link
  • Multi-Item Link
  • Link Recovery (beta)
  • Modular Link (UK/EU only)
Optimizing Link
  • Optimizing Link conversion
  • Link analytics and tracking
  • Pre-Link messaging
  • Customizing Link
  • Choosing when to initialize products
Errors and troubleshooting
  • Troubleshooting
  • Handling an invalid Link Token
  • Institution status in Link
Legacy flows
  • Legacy public key integrations
  • Link Token migration guide
  • Webview integrations
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
  • What's the difference between Plaid Identity and IDV?
  • How do I set up a webhook for IDV?
  • How do I fix an Item in ITEM_LOGIN_REQUIRED state?
Note: Bill isn't perfect. He's just a robot platypus that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
Plaid.com
Log in
Get API Keys
Open nav

Link Recovery (beta)

Notify users impacted by institution downtime to return to your app and link their accounts

Overview

Link Recovery (beta) allows you to provide a superior user experience and improved conversion when users run into issues connecting with an institution. When a user attempts to connect an institution that is experiencing a temporary connectivity outage, Link Recovery lets the user opt in to receiving an email notification from Plaid letting them know when the issue has been resolved. The user can then launch Link directly from a link in the email notification and complete the process of connecting their account.

Link Recovery is designed to be easy to implement and can be added to an existing Plaid integration with only a few lines of code.

The user encounters an error because their institution is down.
The user encounters an error because their institution is down.
They elect to be notified when the problem is resolved.
They exit Link...
...and receive a confirmation email.
When the institution is back up, they are notified...
...and can click a link in the email to go directly to Link.
They connect to the institution...
...select their account...
...and receive a success screen with a button to redirect them to your app.

Link Recovery is currently in beta. To request access, complete this short Google form.

Integration steps

Calling /link/token/create

When calling /link/token/create, specify the following, in addition to your normal parameters:

  • A webhook URI, where you will receive the SESSION_FINISHED webhook used to deliver the public_token for Link Recovery sessions.
  • (Optional) A hosted_link.completion_redirect_uri, indicating the URI that the user should be redirected to after completing a Link Recovery session. This field is optional, but strongly recommended; you can use it to redirect the user to your app so they can see the impact of linking their account.
  • If you are not specifying a hosted_link.completion_redirect_uri, include a hosted_link object (an empty object is fine) in the request in order to enable Hosted Link for your session. Link Recovery requires Hosted Link.
Listening for the SESSION_FINISHED webhook

Next, make sure to listen for the SESSION_FINISHED webhook, which will fire when your end user completes their Link Recovery session.

1{
2 "webhook_type": "LINK",
3 "webhook_code": "SESSION_FINISHED",
4 "status": "SUCCESS",
5 "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",
6 "link_token": "link-sandbox-af1a0311-da53-4636-b754-dd15cc058176",
7 "public_tokens": [
8 "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d"
9 ],
10 "environment": "sandbox"
11}

After retrieving the public token from the public_tokens array, you can exchange it as normal.

Testing Link Recovery

Plaid will not send email notifications in the Sandbox environment, so the Link Recovery flow cannot be tested end-to-end in Sandbox. Instead, you can test the two parts of the flow separately.

To test that you are enabled for Link Recovery and that users can sign up to receive emails, log in to Link in Sandbox with the following credentials to simulate a temporary institution outage: username: user_good password: error_INSTITUTION_DOWN. (If you are not yet enabled for Link Recovery, you can also use the following credentials to see the Link Recovery experience in Sandbox: username: user_link_recovery password: {}.)

To test that the Link Recovery session works correctly, call /link/token/create and manually go to the hosted_link_uri present in the response. This will launch a Hosted Link session, where you can test going through the Link flow with the user_good / pass_good credentials and triggering the SESSION_FINISHED webhook.

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