Add Consumer Report to your app

This guide will walk you through onboarding your users to Plaid Check, so you can generate cash flow insights for your customers by creating a Consumer Report.

You can use our official server-side client libraries to connect to the Plaid Check API from your application:

1// Install via npm
2npm install --save plaid

After you've installed these client libraries, initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Your next step is to create a user_token that will represent the end user.

To create a user_token, make a call to the /user/create endpoint. This endpoint requires a unique client_user_id value to represent the current user. Typically, this value is the same identifier you're using in your own application to represent the currently signed-in user.

In addition, you will need to pass in a consumer_report_user_identity object to use Plaid Check products for this user. In this field, you should pass in user identity data that has been provided by your user for consumer report purposes.

You can only create one user_token per client_user_id. If you try to create a user_token with a client_user_id that you have previously sent to this endpoint, you will receive an error.

The /user/create endpoint will return a randomly generated string for both the user_token and the user_id. Make sure to save both values. You send the user_token to Plaid Check to generate reports, and Plaid Check will use the user_id to refer to this user when it sends you a webhook.

Depending on your application, you might wish to create this user_token as soon as your user creates an account, or wait until shortly before your application would want to generate a report for this user.

Link is a client side UI widget that provides a secure, elegant flow to guide your users through the process of connecting Plaid Check with their financial institutions.

Before initializing Link, you will need to create a link_token. A link_token is a short-lived, single-use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint from your server.

When calling /link/token/create, you'll include an object telling Plaid Check about your application as well as how to customize the Link experience. In addition to the required parameters, you will need to provide the following:

• For user_token, provide the user_token you created in the previous step.
• For products, pass in cra_base_report, plus any additional Plaid Check products you wish to use (cra_income_insights, cra_partner_insights, and/or cra_network_insights), along with any additional Plaid Inc. products you are using. Note that Plaid Check products can't be used in the same Link flow with Income or Assets.
• Provide a webhook URL with an endpoint where you can receive webhooks from Plaid Check. Plaid Check will contact this endpoint when your report is ready.
• Include the appropriate options for the products you are using in the cra_options object.
• If you wish to start generating a report as soon as the user is done with the Link process, include a consumer_report_permissible_purpose parameter specifying your purpose for generating an Consumer Report.
• On mobile, specify the redirect_uri and/or android_package_name fields as necessary, per the relevant Link documentation for your platform.

Send the link_token you get back in the response to your client application.

1// Generate the user_token by calling /user/create 
2
3const request: LinkTokenCreateRequest = {
4  user: {
5    client_user_id: 'user-abc',
6    email_address: 'user@example.com'
7  },
8  user_token: 'user-environment-1234567-abcd-abcd-1234-1234567890ab',
9  products: ['cra_income_insights', 'cra_base_report'],
10  consumer_report_permissible_purpose: 'EXTENSION_OF_CREDIT',
11  enable_multi_item_link: 'true',
12  cra_options: {
13    days_requested: 365
14  },
15  client_name: 'The Loan Arranger',
16  language: 'en',
17  country_codes: ['US'],
18  webhook: 'https://sample-web-hook.com'
19};
20try {
21  const response = await plaidClient.linkTokenCreate(request);
22  const linkToken = response.data.link_token;
23} catch (error) {
24  // handle error
25}

If you wish to use Plaid Inc. products (Transactions, Auth, etc.) alongside Plaid Check products, you can. You can just add those products to the appropriate products array when sending a request to /link/token/create. Link will take the user through a hybrid flow, where we establish connections to both Plaid Check and Plaid Inc. at the same time. One exception is that you cannot use the Plaid Inc. Income or Assets in the same session as a Plaid Check product. Instead, you should use the similar CRA Income Insights or CRA Base Consumer Report products.

Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the appropriate section in the Link documentation.

You will need to install the Link JavaScript library in order to use Link in your web application.

1<head>
2  <title>Extend my Credit</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>

To run Link, you'll first need to retrieve the link_token from the server as described above. Then call Plaid.create(), passing along that token alongside other callbacks you might want to define. This will return a handler that has an open method. Call that method to open up the Link UI and start the connection process.

1const linkHandler = Plaid.create({
2  token: link_token_from_previous_step,
3  onSuccess: (public_token, metadata) => {
4    // Typically, you'd exchange the public_token for an access token.
5    // You won't do that with Plaid Check products.
6  },
7  onExit: (err, metadata) => {
8    // Optionally capture when your user exited the Link flow.
9    // Storing this information can be helpful for support.
10  },
11  onEvent: (eventName, metadata) => {
12    // Optionally capture Link flow events, streamed through
13    // this callback as your users connect an Item to Plaid Check.
14  },
15});
16
17linkHandler.open();

If you've used Link in the past with products created by Plaid, you're probably used to taking the public_token received from Link and exchanging it on your server for a persistent access_token. That is not necessary for products created by Plaid Check, and is only necessary if you are using the hybrid flow, where you are using Plaid Inc. products (Transactions, Auth, etc.) alongside Plaid Check products.

If you have included the consumer_report_permissible_purpose flag in your /link/token/create configuration, Plaid Check will start generating the Consumer Report for your user once they have completed the Link process.

You may not want this behavior, however. There might be times where it makes sense to have your user connect to their banks through Plaid Check early in their onboarding process, but wait until later to generate the actual report.

If that's the case, you can omit the consumer_report_permissible_purpose flag from your /link/token/create call. Then, when it's more appropriate for your application to generate a report, call /cra/check_report/create, passing along the user_token you created earlier.

After a user has finished using Link, it may take some time before the Consumer Report is available for you to retrieve. Listen for the CHECK_REPORT_READY webhook to know when it is safe to request the appropriate set of product data.

1app.post('/server/receive_webhook', async (req, res, next) => {
2  const product = req.body.webhook_type;
3  const code = req.body.webhook_code;
4  if (product === 'CHECK_REPORT') {
5    if (code === 'CHECK_REPORT_READY') {
6      const userId = req.body.user_id;
7      // It is now okay to start fetching Consumer Report data for this user
8      fetch_cra_report_for_user(userId);
9    } else if (code === 'CHECK_REPORT_FAILED') {
10      const userId = req.body.user_id;
11      // Handle this error appropriately
12      report_error_with_generating_report(userId);
13    }
14  }
15  // Handle other types of webhooks
16});

The user_id value included in this webhook is the same user_id that was returned from the /user/create call.

Once Plaid Check has informed you that your report is ready, you can use one of the Plaid Check product endpoints (/cra/check_report/base_report/get, /cra/check_report/income_insights/get, or /cra/check_report/partner_insights/get) to retrieve the appropriate cash flow insights. You can attempt to retrieve any type of product data, even if you didn't initialize it in the products array when you called /link/token/create. However, retrieving new products might incur some latency as Plaid Check generates the new insight data.

If you would like your Consumer Report to include information from multiple institutions, the simplest way is to add the enable_multi_item_link: true flag to your /link/token/create call to enable Multi-Item Link. Your user will then have the option to connect to as many institutions as they wish during their Link session, and the generated report will contain data from each institution that the user connects to.

If your user wants to add additional institutions after their initial Link session, you may do so by once again generating a Link token (using the same user_token as before, and including at least one Plaid Check product in the products array), and opening a new Link session on the client.

If you include a consumer_report_permissible_purpose flag in this new Link token, Plaid Check will start generating a new report for your user when they are done with this Link session. However, this report will only contain data from the institution that the user connected to during this most recent Link session.

In the more likely scenario that you want to generate a full report that includes data from all institutions that the user has connected to, you should not include a consumer_report_permissible_purpose flag in this new Link token. Instead, when the user is done, re-generate your Consumer Report by calling /cra/check_report/create as described in the Generating updated reports section below.

Because Consumer Report information is heavily dependent on income data, Plaid recommends using the test accounts designed for producing realistic looking income data, such as user_bank_income (with the password {}). The basic Sandbox credentials (user_good/pass_good) do not return good income data.

Plaid also has additional test users to represent different levels of creditworthiness. For details, see Credit and Income testing credentials.

If, after some time has passed, you wish to generate a new report with updated data (or a user has connected additional institutions), you can do so by performing the following steps:

1. Generate the new report by calling /cra/check_report/create with the same user_token you used earlier.
2. Wait for the CHECK_REPORT_READY webhook.
3. Once you have received the webhook, use one of the Plaid Check product endpoints (/cra/check_report/base_report/get, /cra/check_report/income_insights/get, or /cra/check_report/partner_insights/get) to retrieve the corresponding product data.