Introduction to the returning user experience

The returning user experience (RUX) streamlines onboarding for users who have already connected a financial account with Plaid. If your application collects the user’s phone number and/or email address before the user enters Plaid Link, you may enable the returning user experience by supplying these values in the user object when calling /link/token/create. These fields will not be stored beyond the lifetime of the Link token (4 hours), but will be hashed and compared against hashed data to determine whether Plaid can recognize the user as having linked Items in the past.

The returning user experience can be enabled to create a streamlined Link experience for users when Plaid already knows which institutions the user has previously connected.

When a user.phone_number is provided via the user request object in the /link/token/create endpoint, Plaid will match that data against previously connected accounts. On the Institution Select screen, institutions that a user has already connected with Plaid will be displayed at the top of the list. In testing, showing previously connected institutions at the top can help boost conversion.

Note that providing an email address, without a phone number, will not enable institution boosting. For best results, and to enable more RUX flows, it is recommended to provide a phone number and email address for each user whenever possible.

In addition to boosting previously connected institutions to the top of the list, there are two flows that a returning user could encounter to streamline the verification process depending on the user data (phone number and/or email address) that you pass to Plaid via /link/token/create and institution eligibility. Both of these flows present the returning user with the institutions they have previously connected, which helps to streamline the institution selection process.

Not all financial institutions are compatible with pre-matched or pre-authenticated RUX. For more details, contact your Plaid Account Manager or file a Support request.

The pre-authenticated RUX flow is available for Auth, Balance, Identity, Transfer, Bank Income, Transactions, Assets, Investments, Liabilities, and Signal. To use pre-authenticated RUX, pass user.phone_number and user.email_address into the user request object in the /link/token/create endpoint. If both a user.phone_number and a user.email_address are matched, and the selected institution is eligible for RUX, the user will be prompted to enter a one-time passcode that’s sent to their mobile device instead of entering a username and password. The pre-authenticated RUX flow may not be offered if Plaid flags the session as requiring additional risk mitigation.

The pre-authenticated RUX flow is not enabled by default. To get started with pre-authenticated RUX, contact your Plaid Account Manager or file a support ticket via the Dashboard.

The pre-matched RUX flow is available for Auth, Balance, Identity, Bank Income, Transactions, Assets, Investments, Liabilities, and Signal. This experience is available to all Plaid developers by default, and requires a user.phone_number to be passed into the user request object in the /link/token/create endpoint. If a user.phone_number is matched, this flow allows the user to skip entering their username for a given financial institution.

RUX cannot be used in the Development environment; it must be tested in Production or in the Sandbox. Real email addresses and phone numbers do not work in the Sandbox. Instead, the Sandbox has been seeded with a test user whose phone number and email address may be used to trigger a returning user flow. This user has the following information:

1{
2  "legal_name": "John Doe",
3  "phone_number": "+14155550123",
4  "email_address": "example@plaid.com"
5}

To enable RUX, include the above test user in the user object of the request body when creating a Link token. In Link, the following institutions can be used to test RUX:

• Platypus Bank RUX Auth (ins_133502) for testing the Pre-authenticated flow
  • The OTP code for the test user is 123456.
• Platypus Bank RUX Match (ins_133503) for testing the Pre-matched flow
  • The password for the test user is pass_good.

When measuring conversion, RUX flows can be distinguished by their emitting the MATCHED_SELECT_INSTITUTION and MATCHED_SELECT_VERIFY_METHOD events. MATCHED_SELECT_VERIFY_METHOD is emitted only by RUX flows; MATCHED_SELECT_INSTITUTION is used during RUX flows or if a routing_number parameter was supplied to /link/token/create. If you are both using RUX and providing a routing_number and need to distinguish between the two situations, check the metadata.match_reason to ensure that the reason is returning_user.

You can distinguish between different RUX flows via events. The MATCHED_CREDENTIAL view or event indicates that a user experienced the pre-matched RUX flow. The MATCHED_MFA view or event indicates that they experienced the pre-authenticated RUX flow. These events also imply that the user selected a matched institution from the select pane.

For more details, see Link SDK documentation. For more information on tracking Link conversion in general, see Improving Link conversion.