Migrate from Bank Income to Plaid Consumer Report 
==================================================

#### Switch to CRA Income Insights for model-driven income attributes and FCRA compliance 

This guide will walk you through how to migrate from accessing bank data with Plaid's [Bank Income](https://plaid.com/docs/income/index.html.md) 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.

#### Advantages of Plaid Consumer Report 

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

Income Insights does not replace Document Income or Payroll Income. Plaid Check products can't be used in the same Link flow as Plaid Inc. credit products such as Plaid Document Income, Payroll Income, Assets, or Statements. If you want to continue using any of those products, create separate [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) requests: one for Plaid Check products, and one for the Plaid Inc. credit products.

Non-credit Plaid products, such as Balance and Auth, can continue to be used in the same Link flow as Plaid Check products, and do not require any special changes to your integration.

#### Prerequisites 

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](https://dashboard.plaid.com/settings/team/products) 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](https://dashboard.plaid.com/overview/request-products) . In order to use Plaid Check, your end users must be in the US and you must be on a custom pricing plan.
    

#### Changes to Plaid Link initialization 

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

1.  Call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) prior to creating a Link token:
    
    *   Include identity info in the `identity` object. At minimum, the following fields must be provided: `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 Enterprise) 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](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request:
    
    *   Include the `user_id` string from [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) .
    *   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`.

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

```python
request = LinkTokenCreateRequest(
  loading_sample=True
)
# create link token
response = client.link_token_create(request)
link_token = response['link_token']
```

```bash
curl -X POST https://sandbox.plaid.com/link/token/create -H 'Content-Type: application/json' -d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "loading_sample": true
}'
```

```ruby
link_token_create_request = Plaid::LinkTokenCreateRequest.new(
  {
    loading_sample: true
  }
)

response = client.link_token_create(
  link_token_create_request
)
link_token = response.link_token
```

```java
LinkTokenCreateRequest request = new LinkTokenCreateRequest()
  .loadingSample(true);

Response response = client
  .linkTokenCreate(request)
  .execute();

String linkToken = response.body().getLinkToken();
```

```go
request := plaid.NewLinkTokenCreateRequest(
  "Sample App App",
  "en",
  []plaid.CountryCode{plaid.COUNTRYCODE_US},
  user,
)
request.SetLoadingSample(true)

linkTokenCreateResp, _, err := client.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute()
if err != nil {
  panic(err)
}
linkToken := linkTokenCreateResp.GetLinkToken();
```

For more details, see the Plaid Check [Implementation guide](https://plaid.com/docs/check/add-to-app/index.html.md) .

##### Adding Consumer Report to existing Items 

To enable an existing Income-enabled Item for Consumer Report, call [/user/create](https://plaid.com/docs/api/users/index.html.md#usercreate) and [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) as described above, but include the Item's `access_token` when calling [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) . 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.

#### Update product API calls and webhook listeners 

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

1.  Add webhook listener endpoints for [USER\_CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_ready) and [USER\_CHECK\_REPORT\_FAILED](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_failed) .
    
    *   Upon receiving the [USER\_CHECK\_REPORT\_READY](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_ready) webhook, call product endpoints such as [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) .
    *   Upon receiving the [USER\_CHECK\_REPORT\_FAILED](https://plaid.com/docs/api/products/check/index.html.md#user_check_report_failed) webhook, call [/user/items/get](https://plaid.com/docs/api/users/index.html.md#useritemsget) to determine why Items are in a bad state. If appropriate, send the user through [update mode](https://plaid.com/docs/link/update-mode/index.html.md) 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](https://docs.google.com/spreadsheets/d/1sjzpbPNjz0bF0Ndaly0tShMFgAZ2M9zdvBcQMlDKJbE/edit?gid=727344192#gid=727344192) to map response fields between the old endpoints and new endpoints.
    

| Income endpoint | Equivalent Plaid Check endpoint |
| --- | --- |
| [/credit/sessions/get](https://plaid.com/docs/api/products/income/index.html.md#creditsessionsget) | None (remove) |
| [/credit/bank\_income/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomeget) | [/cra/check\_report/income\_insights/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportincome_insightsget) and/or [/cra/check\_report/base\_report/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportbase_reportget) |
| [/credit/bank\_income/pdf/get](https://plaid.com/docs/api/products/income/index.html.md#creditbank_incomepdfget) | [/cra/check\_report/pdf/get](https://plaid.com/docs/api/products/check/index.html.md#cracheck_reportpdfget) with `add_ons: ["cra_income_insights"]` |

| Income webhook | Equivalent Plaid Check webhook |
| --- | --- |
| `INCOME_VERIFICATION` | `USER_CHECK_REPORT_READY` |
| `BANK_INCOME_REFRESH_COMPLETE` | `USER_CHECK_REPORT_READY` |

#### API response comparison 

This [Google Sheet](https://docs.google.com/spreadsheets/d/1sjzpbPNjz0bF0Ndaly0tShMFgAZ2M9zdvBcQMlDKJbE/edit?gid=727344192#gid=727344192) 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.