Overview

This article explains the Relink Needed Linked Account status: what it means, why a Linked Account enters it, how to diagnose it, and how an end user can resolve it.

What is Relink Needed?

Relink Needed is a Linked Account status indicating that Merge can no longer successfully sync data from the third-party integration and the end user must re-authenticate to restore the connection. While a Linked Account is in Relink Needed, data syncs between Merge and the integration are paused.

Note: Merge does not charge you for Linked Accounts that are in Relink Needed.

How does an account enter the Relink Needed state?

Merge periodically syncs data according to our sync frequencies and constantly monitors these log requests. A Linked Account will enter a Relink Needed status if there is an open Invalid API key issue or if all the outbound sync requests fail.

What does that mean for data syncs?

Since Merge polls and stores data at regular intervals, a Relink Needed status indicates that our most recent attempt at pulling data was unsuccessful. You would still be able to pull from Merge for data from the most recent successful sync. Until the Relink Needed status is fixed, data syncs between Merge and the integration are effectively paused.

How can the issue be diagnosed?

Merge offers various methods of diagnosing this issue. Our GET /account-details will have a status field that you can use to determine if the account is being flagged as Relink Needed. When a Linked Account is flagged as Relink Needed this will also create an issue that you can see in the Issues tab, through our GET /issues endpoint, or via an Issues Webhook. In most cases, the end user will have to relink the account (we provide a snippet in the Issues tab).

How can a customer relink their account?

To relink an account and prevent creating a new one, you will need to pass the existing account's end_user_origin_id to the /link-token endpoint. That way, when the existing end user opens Merge Link and a new link token is generated, Merge will recognize them and ask for updated credentials to their account instead of setting up a new one.

What happens after a fix is made?

Once the end user relinks the account, our system will attempt to start another sync. If relinking the account does not switch the Linked Account back to Complete (shown as Linked in the Merge dashboard), please reach out to our support team.