On this page

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

One person, many User IDs: engineering solution

Standardize every source on one immutable, case-consistent user_id so no new duplicate profiles appear. Amplitude's standard identity resolution can't merge two established User IDs, so no in-product action combines their historical activity into one project profile. The fix prevents future splits and the plan below handles the history you already have. Start from the findings in the audit.

Historical User IDs stay separate

Don't try to fix this by changing one existing non-null User ID into another. Amplitude treats the new value as a different user. Deleting a profile removes data rather than merging it.

Prevent new duplicate profiles

  1. Choose the immutable backend account ID as the canonical User ID.
  2. Update every web, mobile, server, and customer data platform mapping to send that exact value and casing.
  3. Stop using email addresses, usernames, or platform-specific identifiers as User IDs.
  4. Add automated tests that compare the analytics User ID with the authenticated account ID.
  5. Repeat the audit after you deploy.

Handle existing history

For analysis inside one standard project, record the change date and account for the break in long-term user analysis. If you must unify historical reporting, work with your data team in a warehouse, where they can apply an approved identity mapping outside the Amplitude user model.

The User Mapping API serves a different case. Customers with the Portfolio add-on can map different project-level User IDs to a global User ID for cross-project analysis. It doesn't rewrite the original user properties or replace correct identity instrumentation. Check Pricing or contact Amplitude Sales if cross-project Portfolio analysis fits your need.

Was this helpful?