How does an account enter relink_needed state?
Merge is periodically syncing data according to our sync frequencies and constantly monitoring these log requests. A linked account will enter a "Relink Needed" status if there is an open "BAD API KEY" issue, or if all the outbound requests for a sync fail.
What does that mean for data syncs?
Since Merge is polling and storing data at regular intervals, a "Relink Needed" status will indicate 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 or through our GET /issues endpoint. In most cases, the end user will have to relink the account (we provide a little snippet in the issues tab).
What do you need to do to allow your customer to relink their account?
To relink an account, and to 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 account.
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 to "Complete", please contact us via Intercom!