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 in December 2025 or later, you’ll use these updated APIs to build your integration.

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

• No action is required.
• Your existing integration remains fully supported. Plaid is not removing support and your integration will continue to function as expected.
• We’ll share optional migration steps in Q1 2026. Only after that point will you be able to migrate.

Customers with existing user token integrations cannot yet migrate to this new flow. The API changes below are currently described for informational purposes only.

• 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.
• Coming soon, the user APIs will include net-new endpoints and additional functionality to simplify user management.

• 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.

As of December 10, 2025, all Plaid customers will experience the new user API behavior by default, with the following exceptions:

• Any existing Plaid customers who ever used the /user/create endpoint in either Sandbox or Production as of December 10, 2025, will automatically be kept on the old user API behavior, to avoid breaking changes. This group includes all existing and currently integrating customers of Consumer Report, Multi-Item Link, and/or Income Verification.

• After December 10, 2025, any new customers of Plaid Income Verification will automatically be moved to the older user APIs, since the new user APIs will not be ready for Plaid Income Verification until Q1 2026. Note that this applies only to the legacy Plaid Income Verification product; it does not apply to the Plaid Check Consumer Report Income modules, such as Base Report and Income Insights.

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 beginning December 10, 2025 or later should use the new user_id based implementation currently described in the docs.

Existing clients should take no action at this time. Migration will be optional (though recommended) and available after Q1 2026.

More information will be provided about the new user APIs in Q1 2026. In the meantime, if you have questions about timing, readiness, or how Plaid's new user APIs might benefit your integration, contact your Plaid Account Manager.