Ask Bill!

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_stage you plan to use it for (PREQUALIFICATION and/or DECISIONING). 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_REPORT webhooks.

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 the Plaid libraries
// 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.

server.js
// 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.

ScopeItems usedHow you get the report
CLIENT_USEROnly the Items the user linked through your applicationThe user completes Link, Plaid Check sends a CRA_REPORT_READY webhook, and you call /cra/report/get
PLAID_NETWORKThe 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:

  • name
  • date_of_birth
  • emails
  • phone_numbers
  • addresses

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.

server.js
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 the user_id you 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/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 Assets or Income.
  • 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 a cra_report_parameter object describing the report you want to generate. This object replaces cra_options; do not send both.
  • Include a consumer_report_permissible_purpose parameter specifying your purpose for generating a Consumer Report. It must be compatible with the decision_stage in cra_report_parameter.
  • 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.

server.js
// 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:

FieldRequiredDescription
scopeYesMust be CLIENT_USER. PLAID_NETWORK is not supported on /link/token/create.
decision_stageYesPREQUALIFICATION or DECISIONING. Determines which permissible purposes are allowed.
days_requestedNoDays of history to include, up to 731. Values below 180 are raised to 180.
days_requiredNoMinimum days of data required for the report to generate successfully, up to 184.
client_report_idNoYour 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_investmentsNoExtract investment data from the linked accounts.
include_identity_matchNoInclude identity match results for all products in the report that contain identity information. Defaults to false.
productsNoThe 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_stageAllowed consumer_report_permissible_purpose values
PREQUALIFICATIONWRITTEN_INSTRUCTION_PREQUALIFICATION
DECISIONINGELIGIBILITY_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.

index.html
<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.

app.js
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:

FieldDescription
report_idThe identifier of the report. Pass this value to /cra/report/get.
client_report_idThe client_report_id you supplied, if any.
user_id, client_user_idThe user the report belongs to.
scopeCLIENT_USER or PLAID_NETWORK.
successful_productsThe products (with versions) that were generated.
failed_productsThe products (with versions) that failed to generate. Error details are returned in the product's errors when you call /cra/report/get.
generated_timeWhen the products were generated. null if no products succeeded.
error_codePopulated 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.
environmentsandbox or production.
webhookServer.js
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, and consumer_report_permissible_purpose must match the values used to generate the report. Otherwise, the call returns an INVALID_FIELD error.
  • The products array must contain all or a subset of the report's products. Omit product options; the options used to generate the report already apply.
server.js
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:

FieldDescription
product, versionThe product and version this entry describes.
attributesThe insights for this product. Fields vary by product and version. For cra_lend_score, scores are returned in a scores array instead.
itemsInstitution, Item, and account details for products that include them, such as cra_base_report and cra_income_insights.
metadataDetails 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.
errorsEmpty 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.

server.js
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 codeWhat to do
DECISION_STAGE_NOT_ENABLEDContact your Plaid account manager to enable the decision stage for that product.
INVALID_USER_IDENTITYCorrect the user's identity with /user/update, then retry.
NO_MATCHING_USERPLAID_NETWORK only. Send the user through Link instead.
NO_ELIGIBLE_ITEMS_ON_PROFILEPLAID_NETWORK only. Send the user through Link instead.
PRODUCT_GENERATION_FAILEDEvery requested product failed. When only some products fail, the error appears in each product's errors array instead.
USER_ON_SECURITY_FREEZEThe user must lift the security freeze through the Plaid Check Consumer Service Center.
USER_ON_IDENTITY_THEFT_OR_FRAUD_BLOCKThe user must remove the block through the Plaid Check Consumer Service Center.
INVALID_CRA_REPORT_TOKENMake sure that the report_id corresponds to the correct user and environment of the request.
REPORT_NOT_READYThe report hasn't been generated yet. Wait for the CRA_REPORT_READY webhook.
REPORT_NOT_FOUNDNo report exists corresponding to the request. Generate a new one with /cra/report/create.
REPORT_EXPIREDThe report you are attempting to retrieve has expired. Generate a new one with /cra/report/create.
PRODUCT_NOT_REQUESTEDAt 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_UNAVAILABLEThere 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_USERCLIENT_USER only: the provided user has no eligible items connected. Send the user through Link to add their accounts.
ITEM_LOGIN_REQUIREDCLIENT_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.

server.js
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:

  1. Generate the new report by calling /cra/report/create with the same user_id you used earlier and a new client_report_id. The response includes the new report_id.
  2. Wait for the CRA_REPORT_READY webhook.
  3. Once you have received the webhook, call /cra/report/get with the report_id to retrieve the updated product data.
server.js
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_id for each report.
  • Some failures require action from the user before a new report can succeed, such as repairing an Item in update mode.