Migrate from Transactions to Plaid Consumer Report

This guide will walk you through how to migrate from accessing bank data with Plaid's Transactions product to generating Base Reports with Plaid's Consumer Report product.

The CRA Base Report includes account balance, account ownership, and transaction data, and is designed for use cases that require FCRA-compliant consumer reporting, such as tenant screening, income verification, and credit decisioning.

While the Transactions product gives you historical transaction data, the CRA Base Report enhances this by:

• Supporting FCRA-compliant usage
• Bundling additional data (identity, balance, account metadata) in a single report
• Managing the explicit consumer consent and disclosures required for underwriting use cases in the US

If your use case involves evaluating the financial standing of US-based end users for underwriting, credit, or leasing, you should use the CRA Base Report instead of Transactions.

1. To use Consumer Report, it is strongly recommended to update your Plaid client library to the latest version. The minimum required versions for new Consumer Report integrations are:

   • Python: 38.0.0
   • Go: 41.0.0
   • Java: 39.0.0
   • Node: 41.0.0
   • Ruby: 45.0.0

2. Confirm you have access to Plaid Check products in Production. If not, request access via the Dashboard.

When using Plaid Check products, you must create a user before initializing Link. This allows Plaid to associate multiple Items with a single user.

1. Call /user/create before /link/token/create .

   • Include the identity object. At minimum, the following fields must be provided and non-empty: name, date_of_birth, emails, phone_numbers, and addresses (with at least one email address, phone number, and address designated as primary). If you intend to share the report with a GSE (Government-Sponsored Entity) such as Fannie or Freddie, the full SSN is also required via the id_numbers field. For all use cases, providing at least a partial SSN is highly recommended, since it improves the accuracy of matching user records during compliance processes such as file disclosure, dispute, or security freeze requests.
   • Store the user_id in your database.

2. Update your /link/token/create call:

   • Remove the transactions object (if present) from the call.
   • Include the user_id from /user/create.
   • Replace transactions with cra_base_report (and any other CRA products) in the products array.
   • Add a cra_options object with days_requested (min 180).
   • Provide a consumer_report_permissible_purpose.
   • (Optional) To allow multi-institution linking, set enable_multi_item_link to true.

const request: LinkTokenCreateRequest = {
  loading_sample: true
};
try {
  const response = await plaidClient.linkTokenCreate(request);
  const linkToken = response.data.link_token;
} catch (error) {
  // handle error
}

To enable an existing Transactions-enabled Item for Consumer Report, call /user/create and /link/token/create as described above, but include the Item's access_token when calling /link/token/create. When Link is launched, the end user will go through the Consumer Report consent flow, and on successful completion of the flow, the Item will be enabled for Consumer Report.

1. Update your webhook listener endpoints, adding listeners for Plaid Check.

   • Upon receiving the USER_CHECK_REPORT_READY webhook, call product endpoints such as /cra/check_report/base_report/get or (if using) /cra/check_report/partner_insights/get.

   • Upon receiving the USER_CHECK_REPORT_FAILED webhook, call /user/items/get to determine why Items are in a bad state. If appropriate, send the user through update mode to repair the Item.

2. If you're still using other Plaid products like Auth or Balance, continue retrieving and exchanging the public token. Otherwise, it's no longer needed.

This Google Sheet highlights the correspondences between Transactions and CRA Base Report schemas.

If you are using other Plaid Inc. products, note that the account_id returned in API responses from endpoints prefixed with /cra/ will not match the account_id returned in responses from non-CRA Plaid endpoints.

There is no way to directly migrate an existing Transactions-enabled Item to Plaid Check. Instead, you must delete the old Item using /item/remove and prompt the user to go through the Link flow again, using a Link token that is enabled for Plaid Check.

If you are ready to migrate all Items, use /item/remove to delete the Transactions-enabled Items, and prompt your users to return to your app to re-add their accounts using the new Plaid Check-enabled flow. You can also perform this process in stages, disabling only a percentage of Items at a time.

The most conservative gradual migration strategy is to not delete the Transactions-enabled Item until it is in an unhealthy state that requires user interaction to fix (e.g. ITEM_LOGIN_REQUIRED). At that time, instead of sending the Item through update mode, delete the Item using /item/remove and prompt your users to re-add their accounts using the new Plaid-Check enabled flow.

Depending on your use case and business, you may want to leave existing Transactions-enabled Items in place and perform a gradual migration, as described above. Do not remove Transactions logic unless you are no longer using any Transactions-enabled Items.

1. Remove handling for Transactions webhooks, including SYNC_UPDATES_AVAILABLE, INITIAL_UPDATE, HISTORICAL_UPDATE, DEFAULT_UPDATE, RECURRING_TRANSACTIONS_UPDATE

2. Remove calls to /transactions/ endpoints such as /transactions/get, /transactions/sync, or /transactions/recurring/get, as well as any handling for transactions-specific logic, such as transactions updates and pagination.

3. Remove handling for the TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION error.

4. If you have existing Transactions-enabled Items you will no longer be using, call /item/remove to delete these Items so you will no longer be billed for Transactions.