User APIs

Plaid is updating our APIs to support the next generation of user-based products - such as Plaid Protect - and to create a more unified and consistent experience across our platform. These updates improve multi-product compatibility, simplify debugging, and ensure user identifiers behave consistently across all Plaid products. If you're beginning a new Plaid Check Consumer Report (CRA) or Multi-Item Link integration on or after December 10, 2025, or a new Income integration on or after August 17, 2026, you'll use these updated APIs to build your integration.

If you are an existing customer using Plaid Check or Multi-Item Link before December 10, 2025, or Plaid Income Verification before August 17, 2026, here's what you need to know:

• Your existing integration remains fully supported. Plaid is not removing support and your integration will continue to function as expected.
• Optional migration is now available for Plaid Check, Plaid Income Verification, and Multi-Item Link customers. See the migration guide for step-by-step instructions.

• When calling /user/create, the response includes a single user_id instead of a user_token and a user_id. This user_id is used instead of the user_token to identify the user throughout the Plaid API, including when calling API endpoints or when receiving webhooks.
  • A user_id created on the new API (prefixed with usr_) is not equivalent to a user_id (not prefixed with usr_) created on the old API. If you have not yet migrated to the updated user APIs, you cannot use a user_id in place of a user_token for endpoints that accept either identifier.
• /user/create is now idempotent. In the old flow, when /user/create was called on a client_user_id more than once, it would return an error; it now returns the same user_id as the original call.
• The user schema has an identity object (instead of the consumer_report_user_identity object), which is used in the /user/create and /user/update request bodies. This identity object has a different schema than the consumer_report_user_identity object.

• In the old flow, a client_user_id could never be re-used to create a new user, even if the user token was deleted with /user/remove. In the new flow, once /user/remove has been called on a user_id, a new user can be created for the same client_user_id by calling /user/create.
• The endpoint /user/get has been added, allowing you to retrieve identity details about a user that you have previously created.

• The webhooks CHECK_REPORT_READY and CHECK_REPORT_FAILED have been renamed to USER_CHECK_REPORT_READY and USER_CHECK_REPORT_FAILED.
• For Cash Flow Insights (beta) customers, the different Insights webhooks have been replaced by a single webhook, CASH_FLOW_INSIGHTS_UPDATED, with an insights payload field listing all of the insights received.
• For Income customers, the INCOME_VERIFICATION, INCOME_VERIFICATION_RISK_SIGNALS, and INCOME_VERIFICATION_REFRESH_RECONNECT_NEEDED webhooks have been renamed to USER_INCOME_VERIFICATION, USER_INCOME_VERIFICATION_RISK_SIGNALS, and USER_INCOME_VERIFICATION_REFRESH_RECONNECT_NEEDED.

Existing customers who are migrating will receive both the new and old sets of webhooks in parallel during migration, allowing you to cut over at your own pace.

New Plaid Check and Multi-Item Link integrations use the new User API behavior by default as of December 10, 2025. New Income integrations use the new behavior by default as of August 17, 2026. Existing integrations remain on the old behavior to avoid breaking changes:

• Plaid Check and Multi-Item Link customers who used /user/create in either Sandbox or Production before December 10, 2025 are kept on the old User API behavior unless they migrate.

• Plaid Income Verification customers who used /user/create in either Sandbox or Production before August 17, 2026 are kept on the old User API behavior unless they migrate.

If you aren't sure whether you have the new or old API, call /user/create.

• In the new API, the response will not include a user_token, and your user_id will be formatted with the prefix usr_.
• In the old API, the response will include a user_token, and the user_id will not contain a prefix.

To use the new user APIs with a Plaid client library, the minimum client library versions are:

• Python: 38.0.0
• Go: 41.0.0
• Java: 39.0.0
• Node: 41.0.0
• Ruby: 45.0.0

New clients integrating with Plaid Check or Multi-Item Link beginning December 10, 2025 or later should use the new user_id based implementation currently described in the docs.

New clients integrating with Plaid Income Verification beginning August 17, 2026 or later should use the new user_id based implementation currently described in the docs.

Existing users of other Plaid products who are integrating with Plaid Check, Multi-Item Link, or Plaid Income Verification for the first time on or after the applicable date should use the new user_id based implementation currently described in the docs. They may also need to update their client library versions.

Existing clients already using Plaid Check, Multi-Item Link, or Plaid Income Verification products can now optionally migrate to the new User APIs. Migration is recommended but not required — your existing integration will continue to function. See the migration guide for step-by-step instructions.

If you have questions about migration readiness or how the new user APIs might benefit your integration, contact your Plaid account manager.