Migrate from Bank Income to Plaid Consumer Report

This guide will walk you through how to migrate from accessing bank data with Plaid's Bank Income product to generating Income Insights Reports with Plaid Check's Consumer Reports.

The CRA Income Insights Report offers model-driven attributes such as historical gross and net income, facilitating streamlined debt-to-income calculations and income verification. It enables assessment of financial stability through insights like forecasted income, employer name, income frequency, and predicted next payment date.

Bank Income gives you net income data from both irregular or gig income and W-2 income. The CRA Income Insights Report enhances this by:

• Providing FCRA-compliant insights
• Bundling income calculations (historical average income, forecasted income, predicted next payment date) in a single report

Upgrading to Plaid Consumer Report is recommended for all Bank Income customers whose end users are based in the US. (CRA Income Insights is not available for end users outside the US.)

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

   • Python: 23.0.0
   • Go: 26.0.0
   • Java: 24.0.0
   • Node: 25.0.0
   • Ruby: 29.0.0

2. Confirm that you have access to all required Plaid Check products in the Production environment. If you don't have access to Plaid Check, request access via the Dashboard. In order to use Plaid Check, your end users must be in the US and you must be on a custom pricing plan.

When using Plaid Check products, you must create a user prior to sending the user through Link and initialize Link with the resulting user_token. This allows Plaid to associate multiple Items with a single user.

1. Call /user/create prior to creating a Link token:

   • Include identity info in the consumer_report_user_identity object. All fields are required except for last_4_ssn.
   • Store the user_id and user_token in your database.

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

   • Include the user_token string from /user/create .
   • In the products array, replace income_verification with cra_base_report and cra_income_insights.
   • Remove the income_verification object.
   • Add a cra_options object and specify days_requested (minimum 180).
   • If you haven't already, set webhook to your webhook endpoint listener URL. Unlike Bank Income, Plaid Check requires the use of webhooks.
   • Provide a consumer_report_permissible_purpose
   • (Optional) To allow linking multiple Items in one session, 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
}

For more details, see the Plaid Check Implementation guide.

To enable an existing Income-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.

Unlike Bank Income, Plaid Check uses webhooks with async report generation.

1. Add webhook listener endpoints for CHECK_REPORT_READY and CHECK_REPORT_FAILED.

   • Upon receiving the CHECK_REPORT_READY webhook, call product endpoints such as /cra/check_report/income_insights/get.
   • Upon receiving the 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. Replace any Income endpoints and webhook listeners with the equivalent Plaid Check endpoint or webhook listener, using the API response comparison sheet to map response fields between the old endpoints and new endpoints.

This Google Sheet highlights the correspondences between Bank Income and Plaid Check Income Insights 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.