Choosing how to initialize products

When you create a Link token, you specify which products to initialize Link with by including those products in the /link/token/create request. Which products you specify in the request parameters will impact many aspects of your Plaid integration, including user conversion, institution availability, the latency your user experiences when connecting their accounts in Link, the latency you experience when retrieving data from the API, and which products you will be billed for.

You can also add products to an Item post-Link, which is discussed below.

The table below summarizes the /link/token/create request parameters that determine product initialization in Link:

If a product was not initialized during Link, calling an endpoint for that product will automatically add that product to the Item. For example, if an Item was not initialized with Transactions during Link, calling /transactions/sync or /transactions/get on that Item for the first time will add the Transactions product to the Item.

Some exceptions exist: Identity Verification and Payment Initiation cannot be added post-Link. If you are part of the Data Transparency Messaging beta, you cannot add products post-Link unless you specify them in the Additional Consented Products array.

If you initialize Link with a product that is billed under a one-time or recurring fee model, you will be billed when the Item is created, even if you are not yet using the product's endpoints. There are two exceptions:

• If you specify Auth and/or Identity in the Optional Products array, you will not be billed for them until you use their endpoints (e.g., /auth/get).
• You will not be billed for any products in the Additional Consented Products array until you use their endpoints.

To avoid unwanted charges, do not initialize Link with a product in the Products or Required if Supported Products arrays in Production unless you are sure you are going to use that product.

To learn more about how Plaid bills each product, see Billing.

The products you specify in the Products array will determine which institutions and accounts are available in Link. If you specify multiple products in the Products array, only institutions and accounts supporting all of those products will be available. See the accounts / product support matrix to learn which account types support which products.

To avoid overly filtering the institution and account list, you can use the Required if Supported Products or Optional Products array, or initialize Link with only your required products in the Products array and then call your other products' endpoints later.

If you initialize Link with a product in the Products, Required if Supported Products, or Optional Products array, Plaid will prepare relevant product data during or immediately after Link. Otherwise, Plaid will only begin to fetch data for that product when you call an endpoint for that product, such as /auth/get or /transactions/sync. You can therefore minimize product latency by initializing Link with a given product, as opposed to adding the product to the item post-Link.

Products that require extended account history, such as Transactions and Investments, may take a minute or longer to prepare. If you specify one of these products in the Products or Required if Supported Products array, and then you add another product immediately after the user has exited Link, you may experience higher-than-normal latency when calling the secondary product because the first product is still being prepared.

You can avoid this problem by including the secondary product in the Optional Products array, which allows Plaid to prepare product data in a more efficient manner. For example, if you use Transactions as your primary product, and you intend to add Auth post-Link if the account supports Auth, you should specify Auth in the Optional Products array.

You may want to require one or more secondary products when possible, but avoid excluding users whose financial institution does not support those products from linking their account. To accomplish this behavior, you can specify the secondary products in the Required if Supported Products array.

When a product is specified in the Required if Supported Products array, Plaid will require that product if possible. If the institution the end user is attempting to link supports the secondary product, and the user grants Plaid access to an account at the institution that is compatible with it, Plaid will treat the product as though it was specified in the Products array. If the institution does not support the product, if the user doesn't have accounts compatible with it, or if the user has compatible accounts but doesn't grant access to them, Plaid will ignore the product. (To determine whether a product was successfully added to the Item, you can call /item/get after obtaining your access token and read the Item's Products array.)

For example, if you initialize Link with both Auth and Identity in the Products array, a user will only be able to link an account if both Auth and Identity are supported by their institution, and they will not be able to use flows like Same-day Micro-deposits that require Auth to be initialized by itself. However, if you specify Auth in the Products array and Identity in the Required if Supported Products array, users will be able to link checking and savings accounts at any institution that supports Auth, even if the institution does not support Identity. They will also be able to access flows that require Auth to be initialized by itself, like Same-day Micro-deposits.

If the institution does support both Auth and Identity, Plaid will attempt to initialize the Item with both products. If the institution has an OAuth flow where Identity access can be configured as a separate permission, and the user does not grant access to Identity, the Link attempt will error and the user will be prompted to retry the OAuth flow.

As another example, if Transactions and Auth are both specified in the Products array, users will only be able to link checking or savings accounts, because specifying Auth limits acceptable accounts to checking and savings accounts. However, if Transactions is specified in the Products array and Auth is specified in the Required if Supported Products array, users will be able to link other Transactions-compatible account types, such as credit cards and money market accounts. If they do link a checking or savings account, Plaid will fetch Auth data for that account.

Unlike with the Products and Required if Supported Products arrays, products specified in the Optional Products array are treated as best-effort. If an institution supports the selected products but they cannot be added to the Item (e.g., because of a temporary institution error impacting only some products, or because the user did not grant the required product-specific OAuth permissions), Item creation will succeed in spite of these failures.

Like the Required if Supported Products array, the Optional Products array does not affect institution filtering or account filtering, which means there are no guarantees around product data availability. For example, if you initialize Link with Transactions in the Products array and Auth in the Optional Products array, the resultant Item is guaranteed to support Transactions. However, the Item will not support Auth if the institution and account type do not support Auth, as would be the case if the user had selected a credit card account.

Unlike the Required if Supported Products array, the Optional Products array does not enforce OAuth permissions. If, during the OAuth flow when authenticating with an OAuth-based institution, the user does not grant access to the data needed to support an Optional Product, they will not be required to go through the OAuth flow again to update their permissions. Instead, the Item will be successfully created and the product will be unavailable until you have prompted the user to fix their permissions via Update Mode.

If Auth is specified in the Optional Products array, Auth will only be added to the Item if the institution supports Instant Auth.

If your only reason for omitting a product from the Products array is to increase the number of institutions covered, you should specify the product in the Required if Supported Products array rather than adding the product by calling its endpoint. Initializing both products during Link will make it easier to obtain the consent required at institutions that use OAuth, because the user will be prompted to fix their selections during the OAuth flow if they do not grant the required consent for all products. Initializing both products upfront can also reduce latency, because it allows Plaid to begin fetching data immediately and to optimize the order in which different types of data are requested.

By contrast to the Products and Required if Supported Products arrays, if you specify Auth and Identity in the Optional Products array, you will only be billed for these products if you call their endpoints. If you think that you may want to use Auth and/or Identity for an Item, but it isn't necessary for all users, you should specify the product in the Optional Products array, because doing so will significantly reduce API latency if/when you call the product's endpoints later on.

As an example of when to use the Optional Products array, if your app primarily uses Transactions for budgeting but also uses Auth to transfer funds for a small percentage of users (e.g., paid users), you should specify Transactions in the Products array and Auth in the Optional Products array. This will ensure that all Items support Transactions, while also ensuring that Plaid will collect Auth data for as many users as possible without affecting Link conversion or increasing your Auth bill.

As an example of when not to use the Optional Products array, if your app primarily uses Auth for funds transfers but also offers an optional budgeting add-on that uses Transactions, you should specify Auth in the Products array and then add Transactions to the Item by calling /transactions/sync only once your user opts in to using the budgeting tool. This will prevent you from being billed for Transactions before you are sure you need to use it.

If you have opted in to the Data Transparency Messaging beta, then depending on the permissions that were granted during the original Link flow, you may not be able to initialize an Item with an additional product post-Link simply by calling a product endpoint, as you will need to have obtained the proper consent for that product.

Instead, you should specify this product in the Additional Consented Products array when first calling /link/token/create. If the Item has already been created and the product you need is not in the Item's Consented Products field (which can be checked by calling /item/get, you need to obtain additional user consent, which you can do by sending the user through Update Mode with the Products array updated to include the full set of products you would like to obtain consent for.

Both the Additional Consented Products array and Update Mode methods obtain consent for a product without adding the product to that Item, avoiding any billing or performance implications.

There are some exceptions to the ability to initialize products by calling their endpoints:

• Bank Income and Assets can both be initialized post-Link, but may require re-launching Link to obtain additional consent. See Verifying Bank Income for existing Items and Adding Assets to existing Items.
• Identity Verification and Payment Initiation cannot be initialized post-Link.
• When Auth is initialized post-Link, the main Instant Auth flow can be used, but the less common Instant Match, Automated Micro-deposits, or Same Day Micro-deposits flows cannot be initialized post-Link, as these are interactive flows that require user input.

Some products cannot be initialized alongside other products in the same Link session:

• To use Same Day Micro-deposits, Auth must be the only product Link is initialized with.
• Income can only be initialized alongside other products if using Bank Income; Payroll Income and Document Income cannot be initialized alongside other products.
• Identity Verification and Payment Initiation cannot be initialized alongside any other products. If you need to use these products along with other Plaid products, your user will need to launch the Link flow a second time.

The recommendations below assume that you know upfront that you will want to use all the products listed.

Only specify Auth and Identity in the Products array if Identity data is critical to your fraud detection model. Otherwise, specify Auth in the Products array and specify Identity in the Required if Supported Products array. Initializing Link with only Auth in the Products array gives access to a slightly larger range of institutions than initializing with Auth and Identity together. It also allows you to take advantage of Same Day Micro-deposit verification, which can increase conversion.

If your integration uses the Same-Day Micro-deposits flow, then to maximize conversion, initialize Link with Auth in the Products array, then call /signal/prepare. Otherwise, you can initialize with both Auth and Signal and do not need to call /signal/prepare.

Initialize Link with Auth in the Products array and Identity in the Required if Supported Products array. Then call /signal/prepare. Initializing Link without Identity in the Products array will maximize Link conversion, as described under the Auth and Identity section, and specifying Identity in the Required if Supported Products array will minimize latency when calling the Identity endpoints.

Initialize Link with Assets in the Products array and Auth in the Required if Supported Products array. If Auth ends up not being a supported product, send the user through Link again in order to initialize a separate Item with Auth. This increases the number of institutions available and also allows you to take advantage of Same Day Micro-deposit verification, which can increase conversion.

If you want to get both loan data (such as APRs, balance due, and repayment history) and transaction history from the same account, initialize with whichever product is more important for your use case (Transactions if transaction history is more important, Liabilities if loan data is more important). Then list the other product in the Required if Supported Products array.

Initialize with Bank Income first, then call Transactions endpoints later. If an Item is initialized with Transactions during Link, you will not be able to start the Bank Income flow until the Transactions data pull has completed, which may take up to several minutes.

Initialize with Transactions, then specify Investments in the Required if Supported Products array. This will optimize institution coverage while reducing the latency involved in fetching history for both products. Note that the overwhelming majority of institutions that support Investments also support Transactions.

If using Payroll Income or Document Income, first initialize Link with Income Verification in the Products array to have your user verify their income, then launch Link again with Assets in the Products array, as Payroll Income and Document Income cannot be used with any other products. (Note that the order of these steps does not matter. You can launch Link with Assets and then launch it again with Income Verification.)

If using Bank Income, initialize Link with Assets in the Products array. Then, see the instructions on Verifying Bank Income for existing Items to add Bank Income to the Item. Or, you can initialize Link with Bank Income first and then see the instructions on Getting an Asset Report for an existing Item to add Assets.