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.
   • (Optional) If you want to request a Consumer Report on the same day as the Link session, provide a consumer_report_permissible_purpose. This enables Plaid Check to begin creating the Consumer Report immediately after Link, which minimizes report latency and reduces the risks of Item breakage.
   • (Optional) To allow linking multiple Items in one session, set enable_multi_item_link to true.

1const request: LinkTokenCreateRequest = {
2  loading_sample: true
3};
4try {
5  const response = await plaidClient.linkTokenCreate(request);
6  const linkToken = response.data.link_token;
7} catch (error) {
8  // handle error
9}

For more details, see the Plaid Check Implementation guide.

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

1. If you didn't include consumer_report_permissible_purpose in the /link/token/create call, you will need to manually trigger report generation by calling /cra/check_report/create, specifying a webhook, days_requested quantity, and consumer_report_permissible_purpose. If you did include consumer_report_permissible_purpose, the report will be automatically generated once the Link session has successfully completed and this step is not necessary.

2. 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.

3. 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.