Add Consumer Report to your app
Onboard your users to Plaid Check and retrieve every product with a single call
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 and retrieving it via the /cra/report/get endpoint.
This is designed as a granular, step-by-step walkthrough showing one option for a simple Plaid Check integration for customers new to Plaid. Plaid also offers a no-code integration option and a high-level integration overview.
The endpoints in this guide went live on October 30, 2026. For new implementations on the legacy Plaid Check endpoints, see this legacy implementation guide. If you already use the legacy /cra/check_report/* endpoints, see Migrate from legacy Plaid Check APIs.
Before you begin
To complete this guide, you will need:
- Production or Sandbox access to each Plaid Check product you plan to use, along with the
decision_stageyou plan to use it for (PREQUALIFICATIONand/orDECISIONING). To request access, see Testing Consumer Report or contact your Plaid account manager. - An approved Plaid Check application covering the permissible purpose you will use.
- A webhook endpoint that can receive
CRA_REPORTwebhooks.
Install and initialize Plaid libraries
You can use our official server-side client libraries to connect to the Plaid Check API from your application:
// Install via npm
npm 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.
// Using Express
const express = require('express');
const app = express();
app.use(express.json());
const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
const configuration = new Configuration({
basePath: PlaidEnvironments.sandbox,
baseOptions: {
headers: {
'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
'PLAID-SECRET': process.env.PLAID_SECRET,
},
},
});
const client = new PlaidApi(configuration);
Choose a report scope
Every Consumer Report has a scope, which determines which of the user's Items Plaid Check uses to build the report.
| Scope | Items used | How you get the report |
|---|---|---|
CLIENT_USER | Only the Items the user linked through your application | The user completes Link, Plaid Check sends a CRA_REPORT_READY webhook, and you call /cra/report/get |
PLAID_NETWORK | The Plaid Network view of the user's profile, for users who have consented to faster sharing of their data via Plaid Check Returns only Plaid-derived scores, insights, and attributes, not bank data such as transactions. Base Report is not available with this scope. | Call /cra/report/get directly for a synchronous report, or call /cra/report/create and wait for the webhook for a newly generated one |
Most of this guide covers the CLIENT_USER flow. To retrieve a PLAID_NETWORK report without sending the user through Link, see Retrieving a report without Link.
Create a user
Your next step is to create a user_id that will represent the end user.
To create a user_id, 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 an 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. At minimum, the following fields must be provided:
namedate_of_birthemailsphone_numbersaddresses
At least one email, phone number, and address must be 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.
The /user/create endpoint will return a randomly generated string for the user_id. Make sure to save it. You send the user_id to Plaid Check to generate and retrieve reports, and Plaid Check will use it to refer to this user when it sends you a webhook.
Depending on your application, you might wish to create this user_id as soon as your user creates an account, or wait until shortly before your application would want to generate a report for this user.
const response = await client.userCreate({
client_user_id: 'your-db-id-3b24110',
identity: {
name: { given_name: 'Carmen', family_name: 'Berzatto' },
date_of_birth: '1987-01-31',
emails: [
{ data: 'carmy@example.com', primary: true },
{ data: 'bear@example.com', primary: false },
],
phone_numbers: [{ data: '+14155550011', primary: true }],
addresses: [
{
street_1: '3200 W Armitage Ave',
city: 'Chicago',
region: 'IL',
postal_code: '60647',
country: 'US',
primary: true,
},
],
id_numbers: [{ value: '1234', type: 'us_ssn_last_4' }],
},
});
const userId = response.data.user_id;Integrations that began using /user/create before December 10, 2025 pass consumer_report_user_identity instead of identity and receive a user_token. For details, see New User APIs.
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_id, provide theuser_idyou created in the previous step. - For
products, pass in any Plaid Check products you wish to use (e.g.,cra_base_report,cra_income_insights,cra_cashflow_insights,cra_lend_score, and/orcra_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 Assets or Income. - Provide a
webhookURL with an endpoint where you can receive webhooks from Plaid Check. Plaid Check will contact this endpoint when your report is ready. - Include a
cra_report_parameterobject describing the report you want to generate. This object replacescra_options; do not send both. - Include a
consumer_report_permissible_purposeparameter specifying your purpose for generating a Consumer Report. It must be compatible with thedecision_stageincra_report_parameter. - On mobile, specify the
redirect_uriand/orandroid_package_namefields as necessary, per the relevant Link documentation for your platform.
Send the link_token you get back in the response to your client application.
// Generate the user_id by calling /user/create
const request = {
user_id: 'usr_9nSp2KuZ2x4JDw',
products: ['cra_base_report', 'cra_income_insights'],
consumer_report_permissible_purpose: 'EXTENSION_OF_CREDIT',
enable_multi_item_link: true,
cra_report_parameter: {
scope: 'CLIENT_USER',
decision_stage: 'DECISIONING',
client_report_id: 'loan-app-9981',
days_requested: 184,
products: [
{ product: 'cra_base_report', version: 'V1' },
{
product: 'cra_income_insights',
version: 'V2',
options: {
income_insights_filter: {
included_categories: ['EARNED_INCOME.*'],
excluded_categories: [],
},
},
},
],
},
client_name: 'The Loan Arranger',
language: 'en',
country_codes: ['US'],
webhook: 'https://sample-web-hook.com',
};
try {
const response = await client.linkTokenCreate(request);
const linkToken = response.data.link_token;
} catch (error) {
// handle error
}Configuring the report
The cra_report_parameter object accepts the same report settings as /cra/report/create:
| Field | Required | Description |
|---|---|---|
scope | Yes | Must be CLIENT_USER. PLAID_NETWORK is not supported on /link/token/create. |
decision_stage | Yes | PREQUALIFICATION or DECISIONING. Determines which permissible purposes are allowed. |
days_requested | No | Days of history to include, up to 731. Values below 180 are raised to 180. |
days_required | No | Minimum days of data required for the report to generate successfully, up to 184. |
client_report_id | No | Your own identifier for the report, such as a loan application ID. Returned in the webhook and the report. Use a new value for each report. |
include_investments | No | Extract investment data from the linked accounts. |
include_identity_match | No | Include identity match results for all products in the report that contain identity information. Defaults to false. |
products | No | The Plaid Check products to generate, each with a version and optional options. If omitted, Plaid Check generates the default version of each Plaid Check product in the top-level products array. |
Options for any product in cra_report_parameter.products that isn't in the top-level products array are ignored. Product-specific options include require_identity for cra_base_report, income_insights_filter for cra_income_insights, and variants for cra_lend_score.
When the user completes Link, Plaid Check generates the report based on all items connected in that Link session.
Matching the decision stage and permissible purpose
The decision_stage and consumer_report_permissible_purpose must be compatible on every call to /link/token/create, /cra/report/create, and /cra/report/get.
| decision_stage | Allowed consumer_report_permissible_purpose values |
|---|---|
PREQUALIFICATION | WRITTEN_INSTRUCTION_PREQUALIFICATION |
DECISIONING | ELIGIBILITY_FOR_GOVT_BENEFITS, EXTENSION_OF_CREDIT, LEGITIMATE_BUSINESS_NEED_OTHER, LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING, WRITTEN_INSTRUCTION_OTHER |
An incompatible pairing returns an INVALID_FIELD error. If your account isn't enabled for the requested decision_stage on a product, the call returns a DECISION_STAGE_NOT_ENABLED error instead; contact your Plaid account manager to enable it.
Using Plaid Check products alongside Plaid products
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 products in the same session as a Plaid Check product. Instead, you should use the similar CRA Income Insights or Consumer Report (cra_base_report) products.
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. To integrate with Embedded Link, visit these integration steps.
Install the Link library
You will need to install the Link JavaScript library in order to use Link in your web application.
<head>
<title>Extend my Credit</title>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
</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.
const linkHandler = Plaid.create({
token: link_token_from_previous_step,
onSuccess: (public_token, metadata) => {
// Typically, you'd exchange the public_token for an access token.
// You won't do that with Plaid Check products.
},
onExit: (err, metadata) => {
// Optionally capture when your user exited the Link flow.
// Storing this information can be helpful for support.
},
onEvent: (eventName, metadata) => {
// Optionally capture Link flow events, streamed through
// this callback as your users connect an Item to Plaid Check.
},
});
linkHandler.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.
Generate a report
Plaid Check will start generating the Consumer Report for your user once they have completed the Link process, using the settings in cra_report_parameter.
To generate a new report later, for example to pick up newer data or add products, call /cra/report/create. For details, see Generating updated reports.
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 CRA_REPORT_READY webhook to know when it is safe to retrieve the report.
Plaid Check sends a single CRA_REPORT_READY webhook when generation finishes, whether every product succeeded, only some did, or none did. There is no separate failure webhook. Use the webhook's fields to decide what to do next:
| Field | Description |
|---|---|
report_id | The identifier of the report. Pass this value to /cra/report/get. |
client_report_id | The client_report_id you supplied, if any. |
user_id, client_user_id | The user the report belongs to. |
scope | CLIENT_USER or PLAID_NETWORK. |
successful_products | The products (with versions) that were generated. |
failed_products | The products (with versions) that failed to generate. Error details are returned in the product's errors when you call /cra/report/get. |
generated_time | When the products were generated. null if no products succeeded. |
error_code | Populated only when every product failed: DATA_UNAVAILABLE (sending the user through Link to add or repair Items may resolve this) or INTERNAL_SERVER_ERROR. Otherwise null. |
environment | sandbox or production. |
app.post('/server/receive_webhook', async (req, res, next) => {
const product = req.body.webhook_type;
const code = req.body.webhook_code;
if (product === 'CRA_REPORT' && code === 'CRA_REPORT_READY') {
const {
user_id,
report_id,
scope,
successful_products,
failed_products,
error_code,
} = req.body;
if (error_code) {
// Every product failed (DATA_UNAVAILABLE or INTERNAL_SERVER_ERROR)
handle_report_failure(user_id, error_code);
} else {
// Save the report_id, then retrieve the products that succeeded
fetch_cra_report(user_id, report_id, scope, successful_products);
if (failed_products.length > 0) {
// Optionally retry the failed products with /cra/report/create
queue_retry(user_id, failed_products);
}
}
}
// Handle other types of webhooks
res.sendStatus(200);
});Retrieve report data
Once Plaid Check has informed you that your report is ready, call /cra/report/get to retrieve it. This single endpoint returns every product on the report (unlike the legacy per-product /cra/check_report/*/get endpoints). You are billed for the products you retrieve, so request only the products you need, such as those listed in the webhook's successful_products.
Passing a report_id is required unless you are requesting an Instant Link report via /cra/report/get.
When you pass a report_id:
- The
scope,decision_stage, andconsumer_report_permissible_purposemust match the values used to generate the report. Otherwise, the call returns anINVALID_FIELDerror. - The
productsarray must contain all or a subset of the report's products. Omit productoptions; the options used to generate the report already apply.
try {
const response = await client.craReportGet({
user_id: 'usr_9nSp2KuZ2x4JDw',
report_id: 'cra-report-production-6f8b1e0c-4d2a-4c7e-9a3b-2f1d8e5a7c90',
scope: 'CLIENT_USER',
decision_stage: 'DECISIONING',
consumer_report_permissible_purpose: 'EXTENSION_OF_CREDIT',
products: [
{ product: 'cra_base_report', version: 'V1' },
{ product: 'cra_income_insights', version: 'V2' },
],
});
const report = response.data.report;
} catch (error) {
// handle error
}Reading the response
The response contains user_id, client_user_id, a warnings array, and a report object. The report object echoes the report_id, client_report_id, scope, decision_stage, and consumer_report_permissible_purpose, along with a retrieved_time and a products array with one entry per requested product:
| Field | Description |
|---|---|
product, version | The product and version this entry describes. |
attributes | The insights for this product. Fields vary by product and version. For cra_lend_score, scores are returned in a scores array instead. |
items | Institution, Item, and account details for products that include them, such as cra_base_report and cra_income_insights. |
metadata | Details about the data used, including generated_time, item_count, account_count, institution_ids, account counts by type, and the oldest and most recent transaction dates. |
errors | Empty on success. If the product failed to generate, contains one or more Plaid error objects. |
A request where some products failed still returns HTTP 200. Loop over report.products and check each product's errors array before using its data.
Check the top-level warnings array as well. Possible warning codes are IDENTITY_UNAVAILABLE, TRANSACTIONS_UNAVAILABLE, and USER_FRAUD_ALERT. A USER_FRAUD_ALERT warning means the user has placed a fraud alert on their Plaid Check consumer report, and you are obligated to verify the consumer's identity.
LendScore
To retrieve LendScore, request cra_lend_score with version V2. You can request one or more score variants in options.variants: GENERALIST, SHORT_TERM_LOANS, AUTO, MORTGAGE, and ARC. If you don't specify any variants, GENERALIST is returned.
The scores array contains one entry per variant, each with a variant, score, reason_codes, and error_code. If a variant can't be computed, its score is null and its error_code explains why, such as INSUFFICIENT_TRANSACTION_DATA or NO_ACCOUNTS. New error codes may be added over time, so treat an unrecognized value as a generic failure. For a mapping of reason codes to human-readable reasons, contact your Plaid account manager.
Retrieving a report without Link (via Instant Link)
For users who have already consented to faster sharing of their data via Plaid Check, you can skip Link entirely and go straight from Create a user to /cra/report/get. Set scope to PLAID_NETWORK (the default) and omit report_id. Plaid Check will attempt to match the user to their permissioned Plaid account and return a synchronous report, typically in under two seconds. Some product options, such as LendScore variants, are accepted on this call.
try {
const response = await client.craReportGet({
user_id: 'usr_9nSp2KuZ2x4JDw',
scope: 'PLAID_NETWORK',
decision_stage: 'DECISIONING',
consumer_report_permissible_purpose: 'EXTENSION_OF_CREDIT',
products: [
{
product: 'cra_lend_score',
version: 'V2',
options: { variants: ['GENERALIST', 'SHORT_TERM_LOANS'] },
},
{ product: 'cra_cashflow_insights', version: 'V2' },
{ product: 'cra_network_insights', version: 'V2' },
],
});
} catch (error) {
// NO_MATCHING_USER or NO_ELIGIBLE_ITEMS_ON_PROFILE: fall back to Link
}If Plaid Check can't match the user, the call returns NO_MATCHING_USER. If the matched profile has no eligible Items, it returns NO_ELIGIBLE_ITEMS_ON_PROFILE. In either case, fall back to the Link flow described above.
To generate a new report from the user's Plaid Network Items, call /cra/report/create with scope set to PLAID_NETWORK, then wait for the CRA_REPORT_READY webhook. This takes longer than retrieving a synchronous report.
Handling multiple institutions
If you would like your Consumer Report to include information from multiple institutions, the best 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.
Adding institutions after the initial Link session
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_id as before and a cra_report_parameter object), and opening a new Link session on the client.
Plaid Check will start generating a new report for your user when they are done with the Link session. Because CLIENT_USER reports include every Item the user has linked through your application, the new report will contain data from both the newly connected institution and the institutions from earlier sessions.
Handling errors
Errors returned by the /cra/report/* endpoints have an error_type of CRA_REPORT_ERROR, along with an HTTP 4xx status code.
| Error code | What to do |
|---|---|
DECISION_STAGE_NOT_ENABLED | Contact your Plaid account manager to enable the decision stage for that product. |
INVALID_USER_IDENTITY | Correct the user's identity with /user/update, then retry. |
NO_MATCHING_USER | PLAID_NETWORK only. Send the user through Link instead. |
NO_ELIGIBLE_ITEMS_ON_PROFILE | PLAID_NETWORK only. Send the user through Link instead. |
PRODUCT_GENERATION_FAILED | Every requested product failed. When only some products fail, the error appears in each product's errors array instead. |
USER_ON_SECURITY_FREEZE | The user must lift the security freeze through the Plaid Check Consumer Service Center. |
USER_ON_IDENTITY_THEFT_OR_FRAUD_BLOCK | The user must remove the block through the Plaid Check Consumer Service Center. |
INVALID_CRA_REPORT_TOKEN | Make sure that the report_id corresponds to the correct user and environment of the request. |
REPORT_NOT_READY | The report hasn't been generated yet. Wait for the CRA_REPORT_READY webhook. |
REPORT_NOT_FOUND | No report exists corresponding to the request. Generate a new one with /cra/report/create. |
REPORT_EXPIRED | The report you are attempting to retrieve has expired. Generate a new one with /cra/report/create. |
PRODUCT_NOT_REQUESTED | At least one product was not requested when the report was created. Provide only the products that you requested, or create a new report with the products you want to retrieve. |
DATA_UNAVAILABLE | There is insufficient data to generate a report. Send the user through Link to repair the connection or connect an additional account. |
NO_ELIGIBLE_ITEMS_ON_USER | CLIENT_USER only: the provided user has no eligible items connected. Send the user through Link to add their accounts. |
ITEM_LOGIN_REQUIRED | CLIENT_USER only: the provided user's items are unhealthy. Send the user through Link to repair their connections. |
You should also handle USER_NOT_FOUND, and INVALID_FIELD for missing or mismatched fields.
Correcting user identity
If /cra/report/create or /cra/report/get returns INVALID_USER_IDENTITY, update the user's identity with /user/update and retry the call. Updates are merged: fields you send overwrite the existing values, and fields you omit are left unchanged.
await client.userUpdate({
user_id: 'usr_9nSp2KuZ2x4JDw',
identity: {
phone_numbers: [{ data: '+13125554567', primary: true }],
},
});Testing in Sandbox
All flows in this guide are available in Sandbox starting October 30, 2026.
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. For more test users, see Credit and Income testing credentials. When using special Sandbox test credentials, use a non-OAuth test institution, such as First Platypus Bank (ins_109508).
Testing Instant Link
To test PLAID_NETWORK reports in Sandbox, create the user with the phone number +14155550011 in identity.phone_numbers. Sandbox responses return stubbed data.
In Production, every successful response from /cra/report/get is an FCRA consumer report and is subject to consumer file disclosure.
Generating updated reports
If, after some time has passed, you wish to generate a new report with updated data, add products, or retry products that failed, you can do so without sending the user back through Link by performing the following steps:
- Generate the new report by calling
/cra/report/createwith the sameuser_idyou used earlier and a newclient_report_id. The response includes the newreport_id. - Wait for the
CRA_REPORT_READYwebhook. - Once you have received the webhook, call
/cra/report/getwith thereport_idto retrieve the updated product data.
try {
const response = await client.craReportCreate({
user_id: 'usr_9nSp2KuZ2x4JDw',
scope: 'CLIENT_USER',
decision_stage: 'DECISIONING',
consumer_report_permissible_purpose: 'EXTENSION_OF_CREDIT',
client_report_id: 'loan-app-9981-refresh',
days_requested: 184,
webhook: 'https://sample-web-hook.com',
products: [
{ product: 'cra_base_report', version: 'V1' },
{ product: 'cra_income_insights', version: 'V2' },
],
});
const reportId = response.data.report_id;
} catch (error) {
// handle error
}Keep the following in mind when generating updated reports:
- Plaid Check refreshes an Item's data only if it is more than 24 hours old. Otherwise, the most recent data is reused.
- Use a new
client_report_idfor each report. - Some failures require action from the user before a new report can succeed, such as repairing an Item in update mode.
