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/getcall 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_stagevalues (PREQUALIFICATIONand/orDECISIONING) 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_idfrom/user/create(see New User APIs). If your integration usesuser_tokenwithconsumer_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
| Area | Legacy integration | New integration |
|---|---|---|
| Decision stage | Not part of the request | Set decision_stage to PREQUALIFICATION for prequalification or to DECISIONING for an eligibility decision. |
| Report scope | Reports use only Items linked through your app | Set scope to CLIENT_USER for Items linked through your app, or to PLAID_NETWORK for the user's Plaid Network profile (Instant Link). |
| Product versions | Set per endpoint, sometimes through options | Each product takes a version, such as V2 |
| Base Report contents | Includes NSF and transaction insights | Includes 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 failures | Per-endpoint errors | HTTP 200 with a per-product errors array |
Endpoint and webhook mapping
| Legacy endpoint or webhook | New 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_READYUSER_CHECK_REPORT_FAILEDCHECK_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.
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"
}'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:
| Field | Required | Description |
|---|---|---|
scope | Yes | Must be CLIENT_USER on /link/token/create. |
decision_stage | Yes | PREQUALIFICATION or DECISIONING. |
include_identity_match | No | Include identity match results for products that contain identity. Defaults to false. |
products | No | Products 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_stage | Allowed consumer_report_permissible_purpose values |
|---|---|
PREQUALIFICATION | WRITTEN_INSTRUCTION_PREQUALIFICATION |
DECISIONING | EXTENSION_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).
{
"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"
}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.
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"
}'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.
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" }
]
}'{
"report_id": "cra-report-production-3c9d2a71-8e4f-4b6a-a1d5-7f2c9e0b4d38",
"request_id": "Ga8OaVB9pYvpLqT"
}- Wait for
CRA_REPORT_READY, then call/cra/report/getwith the newreport_id. - To retry only failed products, call
/cra/report/createwith just those products. If a product failed withDATA_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.
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.
- For test users and institutions that return realistic income data, see Testing in Sandbox and Credit and Income testing credentials.
- To test Instant Link, create the user with phone number
+14155550011. To test partial success and failure states, use the numbers in Plaid Check Instant Link testing phone numbers.
