How users connect payroll accounts through Link.
Search is the default user experience in Link.
The user searches from a general list of potential incomes sources. This includes employers, government entities, and payroll services.
- Excluding specific Items or Item categories (employers, gig platforms, payroll providers, or government benefits).
- Limiting search to Items that support deposit switching.
As an alternative to search, Link also supports custom lists:
Create a custom list using Flows in Console.
1flowId: "<ID of the embedded experience>"
Add an array of Item ID's directly within your Link initialization:
1items: ["<ID of Item 1>", "<ID of Item 2>", "..."]
Directly connect users to a specific Item in Link, bypassing search entirely.
- The direct login method has the highest percentage of users that successfully connect a payroll account.
- Recommended whenever the user's employer or payroll provider is already known.
- Create a customized Link Flow in Console with deep-linking enabled.
- Apply saved email/SMS template customizations when sending invites, or copy the ID of a saved embedded experience add it via the
- Add an
itemsarray to your Link initialization with only one Item.
1items: ["<ID of Item 1>"]
1accountId: "<ID of the account>"
In the sample app, a simple employer search bar lets users search for their employer. After making a selection, the user is sent directly to that Item's login screen in Link.
Directly connect users to the document upload screen in Link, bypassing the payroll account connection process. Visit our Document Upload Guide for more information.
Most payroll systems require multi-factor authentication (MFA) when a user logs in or takes action such as updating their direct deposit settings.
- The MFA process can be completed directly within Link.
- Link is designed to be persistent, meaning users can exit Link to retrieve their authentication information, and return to Link seamlessly without their session or the MFA process being interrupted.
Link will display "Connection pending" if an account connection is experiencing significant delays.
- Users will be able to exit Link or return to the search screen to connect additional accounts.
- You can monitor the account's connection status via the API, through the Connections section of Console, or by subscribing to the
accounts.updatedwebhook. The account will have an initial status of
connecting(API) or "Attempted" (Console) until the connection successfully completes or an account connection error occurs.
Expired user token#
If a user delays completing the MFA process for too long, they may encounter the
expired_user_token Link error. Users tokens allow users to exit and return to Link without interruption, but to ensure security, user tokens expire after one hour.
To re-activate Link for the user, create a new user token and either:
- Re-initialize Link with the new user token.
- Pass the user token to the
For more information on customizing the connection process in Link, visit our Flows Guides.