Add Consumer Report to your app
Onboard your users to Plaid Check to generate cash flow insights
This guide will walk you through onboarding your users to Plaid Check, so you can generate cash flow insights for your customers by creating and retrieving Consumer Reports.
Install and initialize Plaid libraries
You can use our official server-side client libraries to connect to the Plaid Check API from your application:
1// Install via npm2npm 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 Express2const express = require('express');3const app = express();4app.use(express.json());56const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');78const 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});1718const client = new PlaidApi(configuration);
Create a user token
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.
Create a Link token
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 theuser_token
you created in the previous step. - For
products
, pass in the Consumer Report(s) you wish to use (cra_base_report
,cra_income_insights
, and/orcra_partner_insights
). - Provide a
webhook
URL with an endpoint where you can receive webhooks from Plaid Check. Plaid Check will contact this endpoint when your reports are ready. - Include the appropriate options for the products you are using in the
cra_options
object. - Make sure to include a
consumer_report_permissible_purpose
specifying your purpose for generating an insights report.
Send the link_token
you get back in the response to your client application.
1const request: LinkTokenCreateRequest = {2 loading_sample: true3};4try {5 const response = await plaidClient.linkTokenCreate(request);6 const linkToken = response.data.link_token;7} catch (error) {8 // handle error9}
Using Plaid Check products alongside Plaid products
If you wish to use Plaid Inc. products (Transactions, Income, 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.
Initialize Link
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.
Install the Link library
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>
Configure the client-side Link handler
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 through13 // this callback as your users connect an Item to Plaid Check.14 },15});1617linkHandler.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.
Listen for webhooks
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 insights.
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 === 'CRA') {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 user8 fetch_cra_report_for_user(userId);9 } else if (code === 'CHECK_REPORT_FAILED') {10 const userId = req.body.user_id;11 // Handle this error appropriately12 report_error_with_generating_report(userId);13 }14 }15 // Handle other types of webhooks16});
The user_id
value included in this webhook is the same user_id
that was returned from the /user/create
call.
Request reports
Once Plaid Check has informed you that your reports are ready, you can use one of the Consumer Report 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 report type, 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.
Generating updated reports
Plaid Check will start generating insight reports for your user once they are done with the Link process. If, after some time has passed, you wish to generate new reports with updated data, you can do so by performing the following steps:
- Call
/cra/check_report/create
with the sameuser_token
you used earlier. - Wait for the
CHECK_REPORT_READY
webhook. - Once you have received the webhook, use one of the Consumer Report endpoints (
/cra/check_report/base_report/get
,/cra/check_report/income_insights/get
, or/cra/check_report/partner_insights/get
) to retrieve the corresponding report.