Ask Bill!

Migrate from legacy Plaid Check APIs

Move a /cra/check_report/* integration to /cra/report/*

Overview

Migration from the legacy /cra/check_report/* APIs to the new /cra/report/* APIs is optional: the legacy endpoints will continue to work. For the full schemas, see the Plaid Check API reference and the legacy Plaid Check API reference.

Why migrate?

After migrating to the new APIs, you can:

  • Get every product from one /cra/report/get call instead of one call per product.
  • Use LendScore V2 when it becomes available (estimated December 2026).
  • Get insights for users who have already opted in to faster sharing through Plaid Check, without an additional login step, using Instant Link.
  • Use the LendScore Complete and Income Complete bundles, which pair credit or income insights with identity information.

Prerequisites

  • Confirm with your Plaid account manager which products and which decision_stage values (PREQUALIFICATION and/or DECISIONING) are enabled for your client. A contract update will be needed to enable your client for decision stages and any additional products that are available via the new APIs.
  • The new endpoints take a user_id from /user/create (see New User APIs). If your integration uses user_token with consumer_report_user_identity, review Migrate to new User APIs first.
  • Minimum client library versions:
    • Python: 45.0.0
    • Node: 48.0.0
    • Ruby: 52.0.0
    • Java: 46.0.0
    • Go: 48.0.0

What's changing

AreaLegacy integrationNew integration
Decision stageNot part of the requestSet decision_stage to PREQUALIFICATION for prequalification or to DECISIONING for an eligibility decision.
Report scopeReports use only Items linked through your appSet scope to CLIENT_USER for Items linked through your app, or to PLAID_NETWORK for the user's Plaid Network profile (Instant Link).
Product versionsSet per endpoint, sometimes through optionsEach product takes a version, such as V2
Base Report contentsIncludes NSF and transaction insightsIncludes Identity Match results when you set include_identity_match to true. No longer includes NSF and transaction insights; use Cash Flow Insights for them.
Partial failuresPer-endpoint errorsHTTP 200 with a per-product errors array

Endpoint and webhook mapping

Legacy endpoint or webhookNew equivalent
/link/token/create with cra_options/link/token/create with cra_report_parameter
/cra/check_report/create/cra/report/create
/cra/check_report/base_report/get/cra/report/get with cra_base_report
/cra/check_report/income_insights/get/cra/report/get with cra_income_insights
/cra/check_report/cashflow_insights/get/cra/report/get with cra_cashflow_insights
/cra/check_report/lend_score/get/cra/report/get with cra_lend_score
/cra/check_report/network_insights/get/cra/report/get with cra_network_insights
USER_CHECK_REPORT_READY
USER_CHECK_REPORT_FAILED
CHECK_REPORT_READY and CHECK_REPORT_FAILED (older user_token integrations)
CRA_REPORT_READY
/cra/check_report/partner_insights/get
/cra/check_report/pdf/get
/cra/check_report/verification/get
/cra/check_report/verification/pdf/get
/cra/monitoring_insights/*
/cra/servicing/*
Cash Flow Updates
Not yet available on new APIs. Support for these endpoints will be rolling out between November 2026 and January 2027.

Migration steps

Update Link token creation

Replace cra_options with cra_report_parameter, and add a decision_stage that matches your permissible purpose.

Before migration
curl -X POST https://sandbox.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "user_id": "usr_9nSp2KuZ2x4JDw",
  "products": ["cra_base_report", "cra_income_insights", "cra_lend_score"],
  "consumer_report_permissible_purpose": "EXTENSION_OF_CREDIT",
  "webhook": "https://example.com/webhook",
  "cra_options": { "days_requested": 184 },
  "client_name": "The Loan Arranger",
  "country_codes": ["US"],
  "language": "en"
}'
After migration
curl -X POST https://sandbox.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "user_id": "usr_9nSp2KuZ2x4JDw",
  "products": ["cra_base_report", "cra_income_insights", "cra_lend_score"],
  "consumer_report_permissible_purpose": "EXTENSION_OF_CREDIT",
  "webhook": "https://example.com/webhook",
  "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": []
          }
        }
      },
      { "product": "cra_lend_score", "version": "V1" }
    ]
  },
  "client_name": "The Loan Arranger",
  "country_codes": ["US"],
  "language": "en"
}'

cra_report_parameter keeps the days_requested, days_required, client_report_id, and include_investments fields from cra_options and adds these:

FieldRequiredDescription
scopeYesMust be CLIENT_USER on /link/token/create.
decision_stageYesPREQUALIFICATION or DECISIONING.
include_identity_matchNoInclude identity match results for products that contain identity. Defaults to false.
productsNoProducts with version and optional options (require_identity for Base Report, income_insights_filter for Income Insights, variants for LendScore). If omitted, the default version of each product in the top-level array is used.

Allowed permissible purposes by decision stage. An incompatible pair returns INVALID_FIELD.

decision_stageAllowed consumer_report_permissible_purpose values
PREQUALIFICATIONWRITTEN_INSTRUCTION_PREQUALIFICATION
DECISIONINGEXTENSION_OF_CREDIT, ELIGIBILITY_FOR_GOVT_BENEFITS, INSURANCE_UNDERWRITING, LEGITIMATE_BUSINESS_NEED_OTHER, LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING, WRITTEN_INSTRUCTION_OTHER
Replace the webhook handler

Plaid Check sends one CRA_REPORT_READY webhook when report generation finishes, whether all, some, or none of the products succeeded. It replaces USER_CHECK_REPORT_READY and USER_CHECK_REPORT_FAILED (or CHECK_REPORT_READY and CHECK_REPORT_FAILED on older user_token integrations).

CRA_REPORT_READY webhook
{
  "webhook_type": "CRA_REPORT",
  "webhook_code": "CRA_REPORT_READY",
  "report_id": "cra-report-production-6f8b1e0c-4d2a-4c7e-9a3b-2f1d8e5a7c90",
  "client_report_id": "loan-app-9981",
  "user_id": "usr_9nSp2KuZ2x4JDw",
  "client_user_id": "uid_12345",
  "scope": "CLIENT_USER",
  "successful_products": [
    { "product": "cra_base_report", "version": "V1" },
    { "product": "cra_income_insights", "version": "V2" },
    { "product": "cra_lend_score", "version": "V1" }
  ],
  "failed_products": [],
  "generated_time": "2026-11-02T20:23:59Z",
  "error_code": null,
  "environment": "production"
}
webhookServer.js
if (
  body.webhook_type === 'CRA_REPORT' &&
  body.webhook_code === 'CRA_REPORT_READY'
) {
  if (body.error_code) {
    // Every product failed: DATA_UNAVAILABLE (send user through Link to add or repair Items)
    // or INTERNAL_SERVER_ERROR
    handleReportFailure(body.user_id, body.error_code);
  } else {
    saveReportId(body.user_id, body.report_id);
    fetchReport(
      body.user_id,
      body.report_id,
      body.scope,
      body.successful_products,
    );
    if (body.failed_products.length > 0)
      queueRetry(body.user_id, body.failed_products);
  }
}

Store the report_id.

Replace per-product retrieval

Replace your per-product /cra/check_report/*/get calls with a single /cra/report/get call.

Before migration
curl -X POST https://sandbox.plaid.com/cra/check_report/base_report/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "user_id": "usr_9nSp2KuZ2x4JDw"
}'

curl -X POST https://sandbox.plaid.com/cra/check_report/income_insights/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "user_id": "usr_9nSp2KuZ2x4JDw"
}'

curl -X POST https://sandbox.plaid.com/cra/check_report/lend_score/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "user_id": "usr_9nSp2KuZ2x4JDw"
}'
After migration
curl -X POST https://sandbox.plaid.com/cra/report/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "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" },
    { "product": "cra_lend_score", "version": "V1" }
  ]
}'

To retrieve the report generated after Link, pass the report_id from the webhook and set scope to CLIENT_USER, because scope defaults to PLAID_NETWORK. The scope, decision_stage, and consumer_report_permissible_purpose must match the values used to generate the report. Request only products the report was generated with. Omit product options, because the options set when the report was generated apply.

You're billed for each product you retrieve.

Update your parsers to read each product from report.products[] rather than from separate endpoint responses, and use the product schemas in the API reference to map fields. Before you use a product's data, check its errors array.

For LendScore, request cra_lend_score version V1 until you adopt LendScore V2.

Replace report updates

Replace /cra/check_report/create with /cra/report/create when updating an existing report.

Generate an updated report
curl -X POST https://sandbox.plaid.com/cra/report/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "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": 365,
  "webhook": "https://example.com/webhook",
  "products": [
    { "product": "cra_base_report", "version": "V1" },
    { "product": "cra_income_insights", "version": "V2" },
    { "product": "cra_lend_score", "version": "V1" }
  ]
}'
Response
{
  "report_id": "cra-report-production-3c9d2a71-8e4f-4b6a-a1d5-7f2c9e0b4d38",
  "request_id": "Ga8OaVB9pYvpLqT"
}
  • Wait for CRA_REPORT_READY, then call /cra/report/get with the new report_id.
  • To retry only failed products, call /cra/report/create with just those products. If a product failed with DATA_UNAVAILABLE, send the user through Link update mode to add or repair Items first.
Update error handling

The /cra/report/* endpoints have their own error codes. For details, see Handling errors.

Adopt LendScore V2 (optional)

LendScore V2 will be available in Production starting in December 2026. V2 uses a 1000-2000 scale and adds optional options.variants: GENERALIST, SHORT_TERM_LOANS, AUTO, MORTGAGE. V2 returns GENERALIST by default. To request other variants, list them in options.variants along with GENERALIST. A variant that can't be computed has a null score and an error_code such as INSUFFICIENT_TRANSACTION_HISTORY_30D or BALANCE_UNAVAILABLE. Treat unrecognized error codes as a generic failure.

V1 score cutoffs don't apply to V2's 1000–2000 scale, so validate V2 before you use it in credit decisions. To compare the two versions on the same applications, request both V1 and V2 of cra_lend_score in one report. For the V2 model documentation and reason code list, contact your Plaid account manager. Before you use V2 in decisions, map its reason codes to your adverse action notices.

Add Instant Link (optional)

If a user has already agreed to let Plaid Check share their data for future credit applications, you can retrieve their report without sending them through Link, by calling /cra/report/get right after creating the user. Use scope: PLAID_NETWORK and omit report_id. The report returns synchronously, typically in under two seconds. Instant Link reports don't include Base Report data. Base Report contains the user's account and transaction data, while a PLAID_NETWORK report contains only the scores, insights, and attributes Plaid derives from the user's Plaid Check consumer profile. To get a Base Report, send the user through Link.

Retrieve an Instant Link report
curl -X POST https://sandbox.plaid.com/cra/report/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "user_id": "usr_9nSp2KuZ2x4JDw",
  "scope": "PLAID_NETWORK",
  "decision_stage": "PREQUALIFICATION",
  "consumer_report_permissible_purpose": "WRITTEN_INSTRUCTION_PREQUALIFICATION",
  "products": [
    { "product": "cra_lend_score", "version": "V1" },
    { "product": "cra_cashflow_insights", "version": "V2" },
    { "product": "cra_network_insights", "version": "V2" }
  ]
}'

To generate a fresh network report instead of the synchronous one, call /cra/report/create with scope: PLAID_NETWORK and wait for the webhook. On NO_MATCHING_USER or NO_ELIGIBLE_ITEMS_ON_PROFILE, fall back to the Link flow described in Update Link token creation through Replace per-product retrieval.

Testing in Sandbox

In Production, every successful /cra/report/get response is an FCRA consumer report and is subject to consumer file disclosure. Don't use Production for integration testing.