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.

(An image of "The user encounters an error because their institution is down.")

(An image of "They elect to be notified when the problem is resolved.")

(An image of "They exit Link...")

(An image of "...and receive a confirmation email.")

(An image of "When the institution is back up, they are notified...")

(An image of "...and can click a link in the email to go directly to Link.")

(An image of "They connect to the institution...")

(An image of "...select their account...")

(An image of "...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](https://docs.google.com/forms/d/e/1FAIpQLSfk98Di4SajVIG0xw5gLhEAKyspNBl8fvUrg32QJ7WnIvb9Cw/viewform) .

#### Integration steps 

##### Calling /link/token/create 

When calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) , 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.

Sample SESSION\_FINISHED webhook

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

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: `{}`.)

When prompted for an email address in the Sandbox Link Recovery flow, enter `example@plaid.com` as the email and `123456` as the security code. Note that in the Sandbox environment, no Link Recovery emails will actually be sent.

To test that the Link Recovery session works correctly, call [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) and manually go to the `hosted_link_url` 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.