Merge two users into one

Sometimes one person ends up with two users in your application. Maybe they signed up with a work email and later signed in with Google under a personal one, or they unintentionally signed up again with a subaddress like jane+work@example.com (and Block email subaddresses was not enabled). An administrator for your application can always clean this up by deleting one user and adding what it had to the other, but this is a manual process. It also often meant asking the person to redo their own setup, like re-connecting their Google account or enrolling their authenticator app again.

Now you can do it in one call. Use our Backend API to merge a user⁠ into another, and Clerk moves its email addresses, phone numbers, connected accounts, passkeys, TOTP, backup codes, organization memberships and metadata onto the user you keep, then deletes the duplicate. When both users have a value for the same field, such as a name, password, username, metadata key, or role in an organization, the user you keep retains its current value.

A few things to know:

• A merge can't be undone. Pass dry_run: true to see the merged user before committing to it.
• The response includes the deleted user as it was before the merge, and a new user.merged webhook links the two, so you can keep track of merges in your own backend. Each merge is also recorded as a user.merged event in Admin Logs and Application Logs.
• A merge isn't allowed if either user is managed by Directory Sync or if the user being deleted has an enterprise SSO account. If the Backend API rejects a merge, it returns the reasons.