---
title: "Merge another user into this user"
method: POST
path: "/users/{user_id}/merge"
tags: ["Users"]
---

# Merge another user into this user

`POST /users/{user_id}/merge`

## Request

- Base URL: `https://api.clerk.com/v1`
- URL: `https://api.clerk.com/v1/users/{user_id}/merge`
- Auth: HTTP bearer

Moves the identifications, connected accounts, passkeys, TOTP, backup codes, organization
memberships, membership requests, suggestions and metadata of the user in `from_user_id` onto the
user in the path, then deletes the `from_user_id` user.
Where both users have a value, the user in the path keeps its own. First and last name, profile
image, `external_id`, and the password are taken from the `from_user_id` user only where the user in
the path has none, so if it has no password, the `from_user_id` user's password signs in to it
afterwards. When both users have the same
identifier, the verified copy is kept. The `from_user_id` user's sessions are revoked.
With `dry_run`, the merge is computed and returned but nothing is changed.

A merge cannot be undone. The response's `deleted_user` is the `from_user_id` user as it was before
the merge, so store it if you may need it. It does not include passwords, TOTP secrets, backup codes,
passkeys or connected-account tokens, which cannot be restored. Use `dry_run` to preview a merge.

The merge sends a `user.merged` webhook alongside `user.updated` and `user.deleted`. Webhooks are not
delivered in order, so `user.updated` (the user now owning the `from_user_id` user's emails) can arrive
before `user.deleted`; handle `user.merged` by moving the `from_user_id` user's data to the user rather
than relying on that order. Moved organization memberships keep their ID, so their
`organizationMembership.updated` webhook carries the same membership ID with a different user.

Some users cannot be merged. The request then fails with a 409 `user_merge_not_allowed` error whose
`meta.reasons` lists every reason that applies:
- `user_banned`, `from_user_banned`: either user is banned.
- `user_directory_managed`, `from_user_directory_managed`: either user is linked to a SCIM directory.
- `from_user_enterprise_account`: the `from_user_id` user has a SAML or enterprise SSO account.
- `from_user_billing_payer`: the `from_user_id` user is a billing payer.
- `from_user_student_pack`: the `from_user_id` user has claimed a student pack.
- `too_many_resources`: the users have too many identifications and organization memberships, requests
  and suggestions combined to merge in one request. This reason is returned on its own.
- `same_user`: `from_user_id` is the user in the path.

## Path parameters

- `user_id` string, required

## Request body

- object
  - `from_user_id` string, required: The ID of the user to merge into the user in the path. This user is deleted.
  - `dry_run` boolean: Return the merged user without changing anything.

## Response `200`

Success

- object
  - `user` User, required
    - `id` string, required
    - `object` 'user', required: String representing the object's type. Objects of the same type share the same value.
    - `external_id` string, nullable, required
    - `primary_email_address_id` string, nullable, required
    - `primary_phone_number_id` string, nullable, required
    - `primary_web3_wallet_id` string, nullable, required
    - `username` string, nullable, required
    - `first_name` string, nullable, required
    - `last_name` string, nullable, required
    - `locale` string, nullable
    - `timezone` string, nullable
    - `profile_image_url` string
    - `image_url` string
    - `has_image` boolean, required
    - `public_metadata` object, required
    - `private_metadata` object, nullable
    - `unsafe_metadata` object
    - `email_addresses` EmailAddress[], required
      - `id` string
      - `object` 'email_address', required: String representing the object's type. Objects of the same type share the same value.
      - `email_address` string, required
      - `reserved` boolean, required
      - `verification` union, required
        - object
          - `object` 'verification_otp'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
          - `strategy` 'phone_code' | 'email_code' | 'reset_password_email_code', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `channel` string, nullable: The delivery channel of the code (phone codes only).
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_admin'
          - `status` 'verified', required
          - `strategy` 'admin', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_from_oauth'
          - `status` 'unverified' | 'verified', required
          - `strategy` string, required
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, nullable, required
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_ticket'
          - `status` 'unverified' | 'verified' | 'expired', required
          - `strategy` 'ticket', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_saml'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
          - `strategy` 'saml', required
          - `external_verification_redirect_url` string, nullable
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, nullable
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_email_link'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
          - `strategy` 'email_link', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_scim'
          - `status` 'verified', required
          - `strategy` 'scim', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
      - `linked_to` IdentificationLink[], required
        - `type` string, required
        - `id` string, required
      - `matches_sso_connection` boolean: Indicates whether this email address domain matches an active enterprise connection.
      - `created_at` integer, required: Unix timestamp of creation
      - `updated_at` integer, required: Unix timestamp of creation
    - `phone_numbers` PhoneNumber[], required
      - `id` string
      - `object` 'phone_number', required: String representing the object's type. Objects of the same type share the same value.
      - `phone_number` string, required
      - `reserved_for_second_factor` boolean
      - `default_second_factor` boolean
      - `reserved` boolean, required
      - `verification` union, required
        - object
          - `object` 'verification_otp'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
          - `strategy` 'phone_code' | 'email_code' | 'reset_password_email_code', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `channel` string, nullable: The delivery channel of the code (phone codes only).
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_admin'
          - `status` 'verified', required
          - `strategy` 'admin', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
      - `linked_to` IdentificationLink[], required
        - `type` string, required
        - `id` string, required
      - `backup_codes` string[], nullable
      - `created_at` integer, required: Unix timestamp of creation
      - `updated_at` integer, required: Unix timestamp of creation
    - `web3_wallets` Web3Wallet[], required
      - `id` string
      - `object` 'web3_wallet', required: String representing the object's type. Objects of the same type share the same value.
      - `web3_wallet` string, required
      - `verification` union, required
        - object
          - `object` 'verification_web3'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
          - `strategy` 'web3_metamask_signature' | 'web3_base_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'web3_solana_signature', required
          - `nonce` string, nullable
          - `message` string, nullable
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_admin'
          - `status` 'verified', required
          - `strategy` 'admin', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
      - `created_at` integer, required: Unix timestamp of creation
      - `updated_at` integer, required: Unix timestamp of creation
    - `passkeys` Passkey[], required
      - `id` string
      - `object` 'passkey', required: String representing the object's type. Objects of the same type share the same value.
      - `name` string, required
      - `last_used_at` integer, required: Unix timestamp of when the passkey was last used.
      - `verification` object, nullable, required
        - `object` 'verification_passkey'
        - `status` 'verified', required
        - `strategy` 'passkey', required
        - `nonce` 'nonce'
        - `message` string, nullable
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `verified_at_client` string, nullable
    - `password_enabled` boolean, required
    - `two_factor_enabled` boolean, required
    - `totp_enabled` boolean, required
    - `backup_code_enabled` boolean, required
    - `mfa_enabled_at` integer, nullable, required: Unix timestamp of when MFA was last enabled for this user. It should be noted that this field is not nullified if MFA is disabled.
    - `mfa_disabled_at` integer, nullable, required: Unix timestamp of when MFA was last disabled for this user. It should be noted that this field is not nullified if MFA is enabled again.
    - `password_last_updated_at` integer, nullable: Unix timestamp of when the user's password was last updated.
    - `external_accounts` ExternalAccountWithVerification[], required
      - `object` 'external_account' | 'facebook_account' | 'google_account', required: String representing the object's type. Objects of the same type share the same value.
      - `id` string, required
      - `provider` string, required
      - `identification_id` string, required
      - `provider_user_id` string, required: The unique ID of the user in the external provider's system
      - `approved_scopes` string, required
      - `email_address` string, required
      - `email_address_verified` boolean, nullable: Whether the email was verified by the OAuth provider at creation time. null = unknown (pre-migration data or custom OAuth providers), true = provider confirmed email was verified, false = provider confirmed email was NOT verified
      - `first_name` string, required
      - `last_name` string, required
      - `avatar_url` string: Please use `image_url` instead
      - `image_url` string, nullable
      - `username` string, nullable
      - `phone_number` string, nullable
      - `public_metadata` object, required
      - `label` string, nullable
      - `created_at` integer, required: Unix timestamp of creation
      - `updated_at` integer, required: Unix timestamp of creation
      - `verification` union, required
        - object
          - `object` 'verification_oauth'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
          - `strategy` string, required
          - `external_verification_redirect_url` string
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, required
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_google_one_tap'
          - `status` 'unverified' | 'verified', required
          - `strategy` 'google_one_tap', required
          - `expire_at` integer, nullable, required
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
    - `saml_accounts` SAMLAccount[], required
      - `id` string, required
      - `object` 'saml_account', required: String representing the object's type. Objects of the same type share the same value.
      - `provider` string, required
      - `active` boolean, required
      - `email_address` string, required
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `provider_user_id` string, nullable
      - `last_authenticated_at` integer, nullable: Unix timestamp of last authentication.
      - `public_metadata` object
      - `verification` union, required
        - object
          - `object` 'verification_saml'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
          - `strategy` 'saml', required
          - `external_verification_redirect_url` string, nullable
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, nullable
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_ticket'
          - `status` 'unverified' | 'verified' | 'expired', required
          - `strategy` 'ticket', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
      - `saml_connection` union
        - object
          - `id` string, required
          - `name` string, required
          - `domain` string, required
          - `domains` string[]
          - `active` boolean, required
          - `provider` string, required
          - `sync_user_attributes` boolean, required
          - `allow_subdomains` boolean
          - `allow_idp_initiated` boolean
          - `disable_additional_identifications` boolean
          - `created_at` integer, required: Unix timestamp of creation.
          - `updated_at` integer, required: Unix timestamp of last update.
        - object
          - `id` string, required
          - `name` string, required
          - `domain` string
          - `domains` string[], required
          - `active` boolean, required
          - `provider` string, required
          - `sync_user_attributes` boolean, required
          - `allow_subdomains` boolean
          - `allow_idp_initiated` boolean
          - `disable_additional_identifications` boolean
          - `created_at` integer, required: Unix timestamp of creation.
          - `updated_at` integer, required: Unix timestamp of last update.
    - `enterprise_accounts` EnterpriseAccount[], required
      - `id` string, required
      - `object` 'enterprise_account', required: String representing the object's type. Objects of the same type share the same value.
      - `protocol` 'oauth' | 'saml': The authentication protocol used to sign in.
      - `provider` string, required
      - `active` boolean, required
      - `email_address` string, required
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `provider_user_id` string, nullable: The unique ID of the user in the external provider's system
      - `enterprise_connection_id` string, nullable
      - `public_metadata` object
      - `verification` union, required
        - object
          - `object` 'verification_ticket'
          - `status` 'unverified' | 'verified' | 'expired', required
          - `strategy` 'ticket', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_saml'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
          - `strategy` 'saml', required
          - `external_verification_redirect_url` string, nullable
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, nullable
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_oauth'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
          - `strategy` string, required
          - `external_verification_redirect_url` string
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, required
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
      - `enterprise_connection` union
        - object
          - `id` string, required
          - `protocol` string, required
          - `provider` string, required
          - `name` string, required
          - `logo_public_url` string, nullable, required
          - `domain` string, required
          - `domains` string[]
          - `active` boolean, required
          - `sync_user_attributes` boolean, required
          - `allow_subdomains` boolean, required
          - `allow_idp_initiated` boolean, required
          - `disable_additional_identifications` boolean, required
          - `created_at` integer, required: Unix timestamp of creation.
          - `updated_at` integer, required: Unix timestamp of last update.
        - object
          - `id` string, required
          - `protocol` string, required
          - `provider` string, required
          - `name` string, required
          - `logo_public_url` string, nullable, required
          - `domain` string
          - `domains` string[], required
          - `active` boolean, required
          - `sync_user_attributes` boolean, required
          - `allow_subdomains` boolean, required
          - `allow_idp_initiated` boolean, required
          - `disable_additional_identifications` boolean, required
          - `created_at` integer, required: Unix timestamp of creation.
          - `updated_at` integer, required: Unix timestamp of last update.
      - `last_authenticated_at` integer, nullable: Unix timestamp of last authentication.
    - `organization_memberships` OrganizationMembership[]
      - `id` string, required
      - `object` 'organization_membership', required: String representing the object's type. Objects of the same type share the same value.
      - `role` string, required
      - `role_name` string
      - `permissions` string[], required
      - `public_metadata` object, required: Metadata saved on the organization membership, accessible from both Frontend and Backend APIs
      - `private_metadata` object: Metadata saved on the organization membership, accessible only from the Backend API
      - `organization` Organization, required
        - `object` 'organization', required
        - `id` string, required
        - `name` string, required
        - `slug` string, required
        - `image_url` string
        - `has_image` boolean, required
        - `members_count` integer
        - `missing_member_with_elevated_permissions` boolean
        - `pending_invitations_count` integer
        - `max_allowed_memberships` integer, required
        - `admin_delete_enabled` boolean, required
        - `self_serve_sso_enabled` boolean: Whether this organization can configure self-serve enterprise SSO.
        - `public_metadata` object, required
        - `private_metadata` object
        - `created_by` string
        - `created_at` integer, required: Unix timestamp of creation.
        - `updated_at` integer, required: Unix timestamp of last update.
        - `last_active_at` integer: Unix timestamp of last activity.
        - `role_set_key` string, nullable: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.
      - `public_user_data` OrganizationMembershipPublicUserData: An organization membership with public user data populated
        - `user_id` string, required
        - `first_name` string, nullable, required
        - `last_name` string, nullable, required
        - `profile_image_url` string, nullable, required
        - `image_url` string, required
        - `has_image` boolean, required
        - `identifier` string, nullable
        - `username` string, nullable
        - `banned` boolean
        - `deprovisioned` boolean
      - `created_at` integer, required: Unix timestamp of creation.
      - `updated_at` integer, required: Unix timestamp of last update.
    - `last_sign_in_at` integer, nullable, required: Unix timestamp of last sign-in.
    - `banned` boolean, required: Flag to denote whether user is banned or not.
    - `locked` boolean, required: Flag to denote whether user is currently locked, i.e. restricted from signing in or not.
    - `deprovisioned` boolean: Flag to denote whether user has been deprovisioned and is restricted from signing in.
    - `lockout_expires_in_seconds` integer, nullable, required: The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires.
    - `verification_attempts_remaining` integer, nullable, required: The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining.
    - `updated_at` integer, required: Unix timestamp of last update.
    - `created_at` integer, required: Unix timestamp of creation.
    - `delete_self_enabled` boolean, required: If enabled, user can delete themselves via FAPI.
    - `create_organization_enabled` boolean, required: If enabled, user can create organizations via FAPI.
    - `create_organizations_limit` integer, nullable: The maximum number of organizations the user can create. 0 means unlimited.
    - `last_active_at` integer, nullable, required: Unix timestamp of the latest session activity, with day precision.
    - `legal_accepted_at` integer, nullable, required: Unix timestamp of when the user accepted the legal requirements.
    - `bypass_client_trust` boolean: When set to `true`, the user will bypass Device Trust checks during sign-in.
    - `directories` SCIMUserMetadata[]: All loaded directory links. Omitted when links were not loaded; an empty array means the user has no directory links.
      - `id` string, required: The user's resource ID in this directory.
      - `directory_name` string, required
      - `provider` string, required
      - `enterprise_connection_id` string, nullable, required
      - `groups` object[]: Omitted when groups were not loaded; an empty array means no group memberships.
        - `id` string, required
        - `display_name` string, required
      - `directory_id` string, required: The ID of the directory the user is provisioned from.
      - `directory_enabled` boolean, required: Whether the directory is currently enabled.
      - `external_id` string, nullable, required: The user's external ID as reported by the directory, if any.
    - `directory` SCIMUserMetadata: Metadata describing a user's linkage to a directory. Included in user responses when directory data is requested, and in directory-triggered user webhooks. Its absence does not necessarily mean the user is not managed by a directory.
      - `id` string, required: The user's resource ID in this directory.
      - `directory_name` string, required
      - `provider` string, required
      - `enterprise_connection_id` string, nullable, required
      - `groups` object[]: Omitted when groups were not loaded; an empty array means no group memberships.
        - `id` string, required
        - `display_name` string, required
      - `directory_id` string, required: The ID of the directory the user is provisioned from.
      - `directory_enabled` boolean, required: Whether the directory is currently enabled.
      - `external_id` string, nullable, required: The user's external ID as reported by the directory, if any.
    - `scim` SCIMUserMetadata: Metadata describing a user's linkage to a directory. Included in user responses when directory data is requested, and in directory-triggered user webhooks. Its absence does not necessarily mean the user is not managed by a directory.
      - `id` string, required: The user's resource ID in this directory.
      - `directory_name` string, required
      - `provider` string, required
      - `enterprise_connection_id` string, nullable, required
      - `groups` object[]: Omitted when groups were not loaded; an empty array means no group memberships.
        - `id` string, required
        - `display_name` string, required
      - `directory_id` string, required: The ID of the directory the user is provisioned from.
      - `directory_enabled` boolean, required: Whether the directory is currently enabled.
      - `external_id` string, nullable, required: The user's external ID as reported by the directory, if any.
  - `deleted_user` User, required
    - `id` string, required
    - `object` 'user', required: String representing the object's type. Objects of the same type share the same value.
    - `external_id` string, nullable, required
    - `primary_email_address_id` string, nullable, required
    - `primary_phone_number_id` string, nullable, required
    - `primary_web3_wallet_id` string, nullable, required
    - `username` string, nullable, required
    - `first_name` string, nullable, required
    - `last_name` string, nullable, required
    - `locale` string, nullable
    - `timezone` string, nullable
    - `profile_image_url` string
    - `image_url` string
    - `has_image` boolean, required
    - `public_metadata` object, required
    - `private_metadata` object, nullable
    - `unsafe_metadata` object
    - `email_addresses` EmailAddress[], required
      - `id` string
      - `object` 'email_address', required: String representing the object's type. Objects of the same type share the same value.
      - `email_address` string, required
      - `reserved` boolean, required
      - `verification` union, required
        - object
          - `object` 'verification_otp'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
          - `strategy` 'phone_code' | 'email_code' | 'reset_password_email_code', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `channel` string, nullable: The delivery channel of the code (phone codes only).
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_admin'
          - `status` 'verified', required
          - `strategy` 'admin', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_from_oauth'
          - `status` 'unverified' | 'verified', required
          - `strategy` string, required
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, nullable, required
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_ticket'
          - `status` 'unverified' | 'verified' | 'expired', required
          - `strategy` 'ticket', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_saml'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
          - `strategy` 'saml', required
          - `external_verification_redirect_url` string, nullable
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, nullable
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_email_link'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
          - `strategy` 'email_link', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_scim'
          - `status` 'verified', required
          - `strategy` 'scim', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
      - `linked_to` IdentificationLink[], required
        - `type` string, required
        - `id` string, required
      - `matches_sso_connection` boolean: Indicates whether this email address domain matches an active enterprise connection.
      - `created_at` integer, required: Unix timestamp of creation
      - `updated_at` integer, required: Unix timestamp of creation
    - `phone_numbers` PhoneNumber[], required
      - `id` string
      - `object` 'phone_number', required: String representing the object's type. Objects of the same type share the same value.
      - `phone_number` string, required
      - `reserved_for_second_factor` boolean
      - `default_second_factor` boolean
      - `reserved` boolean, required
      - `verification` union, required
        - object
          - `object` 'verification_otp'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
          - `strategy` 'phone_code' | 'email_code' | 'reset_password_email_code', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `channel` string, nullable: The delivery channel of the code (phone codes only).
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_admin'
          - `status` 'verified', required
          - `strategy` 'admin', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
      - `linked_to` IdentificationLink[], required
        - `type` string, required
        - `id` string, required
      - `backup_codes` string[], nullable
      - `created_at` integer, required: Unix timestamp of creation
      - `updated_at` integer, required: Unix timestamp of creation
    - `web3_wallets` Web3Wallet[], required
      - `id` string
      - `object` 'web3_wallet', required: String representing the object's type. Objects of the same type share the same value.
      - `web3_wallet` string, required
      - `verification` union, required
        - object
          - `object` 'verification_web3'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
          - `strategy` 'web3_metamask_signature' | 'web3_base_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'web3_solana_signature', required
          - `nonce` string, nullable
          - `message` string, nullable
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_admin'
          - `status` 'verified', required
          - `strategy` 'admin', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
      - `created_at` integer, required: Unix timestamp of creation
      - `updated_at` integer, required: Unix timestamp of creation
    - `passkeys` Passkey[], required
      - `id` string
      - `object` 'passkey', required: String representing the object's type. Objects of the same type share the same value.
      - `name` string, required
      - `last_used_at` integer, required: Unix timestamp of when the passkey was last used.
      - `verification` object, nullable, required
        - `object` 'verification_passkey'
        - `status` 'verified', required
        - `strategy` 'passkey', required
        - `nonce` 'nonce'
        - `message` string, nullable
        - `attempts` integer, nullable, required
        - `expire_at` integer, nullable, required
        - `verified_at_client` string, nullable
    - `password_enabled` boolean, required
    - `two_factor_enabled` boolean, required
    - `totp_enabled` boolean, required
    - `backup_code_enabled` boolean, required
    - `mfa_enabled_at` integer, nullable, required: Unix timestamp of when MFA was last enabled for this user. It should be noted that this field is not nullified if MFA is disabled.
    - `mfa_disabled_at` integer, nullable, required: Unix timestamp of when MFA was last disabled for this user. It should be noted that this field is not nullified if MFA is enabled again.
    - `password_last_updated_at` integer, nullable: Unix timestamp of when the user's password was last updated.
    - `external_accounts` ExternalAccountWithVerification[], required
      - `object` 'external_account' | 'facebook_account' | 'google_account', required: String representing the object's type. Objects of the same type share the same value.
      - `id` string, required
      - `provider` string, required
      - `identification_id` string, required
      - `provider_user_id` string, required: The unique ID of the user in the external provider's system
      - `approved_scopes` string, required
      - `email_address` string, required
      - `email_address_verified` boolean, nullable: Whether the email was verified by the OAuth provider at creation time. null = unknown (pre-migration data or custom OAuth providers), true = provider confirmed email was verified, false = provider confirmed email was NOT verified
      - `first_name` string, required
      - `last_name` string, required
      - `avatar_url` string: Please use `image_url` instead
      - `image_url` string, nullable
      - `username` string, nullable
      - `phone_number` string, nullable
      - `public_metadata` object, required
      - `label` string, nullable
      - `created_at` integer, required: Unix timestamp of creation
      - `updated_at` integer, required: Unix timestamp of creation
      - `verification` union, required
        - object
          - `object` 'verification_oauth'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
          - `strategy` string, required
          - `external_verification_redirect_url` string
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, required
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_google_one_tap'
          - `status` 'unverified' | 'verified', required
          - `strategy` 'google_one_tap', required
          - `expire_at` integer, nullable, required
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
    - `saml_accounts` SAMLAccount[], required
      - `id` string, required
      - `object` 'saml_account', required: String representing the object's type. Objects of the same type share the same value.
      - `provider` string, required
      - `active` boolean, required
      - `email_address` string, required
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `provider_user_id` string, nullable
      - `last_authenticated_at` integer, nullable: Unix timestamp of last authentication.
      - `public_metadata` object
      - `verification` union, required
        - object
          - `object` 'verification_saml'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
          - `strategy` 'saml', required
          - `external_verification_redirect_url` string, nullable
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, nullable
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_ticket'
          - `status` 'unverified' | 'verified' | 'expired', required
          - `strategy` 'ticket', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
      - `saml_connection` union
        - object
          - `id` string, required
          - `name` string, required
          - `domain` string, required
          - `domains` string[]
          - `active` boolean, required
          - `provider` string, required
          - `sync_user_attributes` boolean, required
          - `allow_subdomains` boolean
          - `allow_idp_initiated` boolean
          - `disable_additional_identifications` boolean
          - `created_at` integer, required: Unix timestamp of creation.
          - `updated_at` integer, required: Unix timestamp of last update.
        - object
          - `id` string, required
          - `name` string, required
          - `domain` string
          - `domains` string[], required
          - `active` boolean, required
          - `provider` string, required
          - `sync_user_attributes` boolean, required
          - `allow_subdomains` boolean
          - `allow_idp_initiated` boolean
          - `disable_additional_identifications` boolean
          - `created_at` integer, required: Unix timestamp of creation.
          - `updated_at` integer, required: Unix timestamp of last update.
    - `enterprise_accounts` EnterpriseAccount[], required
      - `id` string, required
      - `object` 'enterprise_account', required: String representing the object's type. Objects of the same type share the same value.
      - `protocol` 'oauth' | 'saml': The authentication protocol used to sign in.
      - `provider` string, required
      - `active` boolean, required
      - `email_address` string, required
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `provider_user_id` string, nullable: The unique ID of the user in the external provider's system
      - `enterprise_connection_id` string, nullable
      - `public_metadata` object
      - `verification` union, required
        - object
          - `object` 'verification_ticket'
          - `status` 'unverified' | 'verified' | 'expired', required
          - `strategy` 'ticket', required
          - `attempts` integer, nullable, required
          - `expire_at` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_saml'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
          - `strategy` 'saml', required
          - `external_verification_redirect_url` string, nullable
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, nullable
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
        - object
          - `object` 'verification_oauth'
          - `status` 'unverified' | 'verified' | 'failed' | 'expired' | 'transferable', required
          - `strategy` string, required
          - `external_verification_redirect_url` string
          - `error` object, nullable
            - `message` string, required
            - `long_message` string, required
            - `code` string, required
            - `meta` object
          - `expire_at` integer, required
          - `attempts` integer, nullable, required
          - `verified_at_client` string, nullable
      - `enterprise_connection` union
        - object
          - `id` string, required
          - `protocol` string, required
          - `provider` string, required
          - `name` string, required
          - `logo_public_url` string, nullable, required
          - `domain` string, required
          - `domains` string[]
          - `active` boolean, required
          - `sync_user_attributes` boolean, required
          - `allow_subdomains` boolean, required
          - `allow_idp_initiated` boolean, required
          - `disable_additional_identifications` boolean, required
          - `created_at` integer, required: Unix timestamp of creation.
          - `updated_at` integer, required: Unix timestamp of last update.
        - object
          - `id` string, required
          - `protocol` string, required
          - `provider` string, required
          - `name` string, required
          - `logo_public_url` string, nullable, required
          - `domain` string
          - `domains` string[], required
          - `active` boolean, required
          - `sync_user_attributes` boolean, required
          - `allow_subdomains` boolean, required
          - `allow_idp_initiated` boolean, required
          - `disable_additional_identifications` boolean, required
          - `created_at` integer, required: Unix timestamp of creation.
          - `updated_at` integer, required: Unix timestamp of last update.
      - `last_authenticated_at` integer, nullable: Unix timestamp of last authentication.
    - `organization_memberships` OrganizationMembership[]
      - `id` string, required
      - `object` 'organization_membership', required: String representing the object's type. Objects of the same type share the same value.
      - `role` string, required
      - `role_name` string
      - `permissions` string[], required
      - `public_metadata` object, required: Metadata saved on the organization membership, accessible from both Frontend and Backend APIs
      - `private_metadata` object: Metadata saved on the organization membership, accessible only from the Backend API
      - `organization` Organization, required
        - `object` 'organization', required
        - `id` string, required
        - `name` string, required
        - `slug` string, required
        - `image_url` string
        - `has_image` boolean, required
        - `members_count` integer
        - `missing_member_with_elevated_permissions` boolean
        - `pending_invitations_count` integer
        - `max_allowed_memberships` integer, required
        - `admin_delete_enabled` boolean, required
        - `self_serve_sso_enabled` boolean: Whether this organization can configure self-serve enterprise SSO.
        - `public_metadata` object, required
        - `private_metadata` object
        - `created_by` string
        - `created_at` integer, required: Unix timestamp of creation.
        - `updated_at` integer, required: Unix timestamp of last update.
        - `last_active_at` integer: Unix timestamp of last activity.
        - `role_set_key` string, nullable: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.
      - `public_user_data` OrganizationMembershipPublicUserData: An organization membership with public user data populated
        - `user_id` string, required
        - `first_name` string, nullable, required
        - `last_name` string, nullable, required
        - `profile_image_url` string, nullable, required
        - `image_url` string, required
        - `has_image` boolean, required
        - `identifier` string, nullable
        - `username` string, nullable
        - `banned` boolean
        - `deprovisioned` boolean
      - `created_at` integer, required: Unix timestamp of creation.
      - `updated_at` integer, required: Unix timestamp of last update.
    - `last_sign_in_at` integer, nullable, required: Unix timestamp of last sign-in.
    - `banned` boolean, required: Flag to denote whether user is banned or not.
    - `locked` boolean, required: Flag to denote whether user is currently locked, i.e. restricted from signing in or not.
    - `deprovisioned` boolean: Flag to denote whether user has been deprovisioned and is restricted from signing in.
    - `lockout_expires_in_seconds` integer, nullable, required: The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires.
    - `verification_attempts_remaining` integer, nullable, required: The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining.
    - `updated_at` integer, required: Unix timestamp of last update.
    - `created_at` integer, required: Unix timestamp of creation.
    - `delete_self_enabled` boolean, required: If enabled, user can delete themselves via FAPI.
    - `create_organization_enabled` boolean, required: If enabled, user can create organizations via FAPI.
    - `create_organizations_limit` integer, nullable: The maximum number of organizations the user can create. 0 means unlimited.
    - `last_active_at` integer, nullable, required: Unix timestamp of the latest session activity, with day precision.
    - `legal_accepted_at` integer, nullable, required: Unix timestamp of when the user accepted the legal requirements.
    - `bypass_client_trust` boolean: When set to `true`, the user will bypass Device Trust checks during sign-in.
    - `directories` SCIMUserMetadata[]: All loaded directory links. Omitted when links were not loaded; an empty array means the user has no directory links.
      - `id` string, required: The user's resource ID in this directory.
      - `directory_name` string, required
      - `provider` string, required
      - `enterprise_connection_id` string, nullable, required
      - `groups` object[]: Omitted when groups were not loaded; an empty array means no group memberships.
        - `id` string, required
        - `display_name` string, required
      - `directory_id` string, required: The ID of the directory the user is provisioned from.
      - `directory_enabled` boolean, required: Whether the directory is currently enabled.
      - `external_id` string, nullable, required: The user's external ID as reported by the directory, if any.
    - `directory` SCIMUserMetadata: Metadata describing a user's linkage to a directory. Included in user responses when directory data is requested, and in directory-triggered user webhooks. Its absence does not necessarily mean the user is not managed by a directory.
      - `id` string, required: The user's resource ID in this directory.
      - `directory_name` string, required
      - `provider` string, required
      - `enterprise_connection_id` string, nullable, required
      - `groups` object[]: Omitted when groups were not loaded; an empty array means no group memberships.
        - `id` string, required
        - `display_name` string, required
      - `directory_id` string, required: The ID of the directory the user is provisioned from.
      - `directory_enabled` boolean, required: Whether the directory is currently enabled.
      - `external_id` string, nullable, required: The user's external ID as reported by the directory, if any.
    - `scim` SCIMUserMetadata: Metadata describing a user's linkage to a directory. Included in user responses when directory data is requested, and in directory-triggered user webhooks. Its absence does not necessarily mean the user is not managed by a directory.
      - `id` string, required: The user's resource ID in this directory.
      - `directory_name` string, required
      - `provider` string, required
      - `enterprise_connection_id` string, nullable, required
      - `groups` object[]: Omitted when groups were not loaded; an empty array means no group memberships.
        - `id` string, required
        - `display_name` string, required
      - `directory_id` string, required: The ID of the directory the user is provisioned from.
      - `directory_enabled` boolean, required: Whether the directory is currently enabled.
      - `external_id` string, nullable, required: The user's external ID as reported by the directory, if any.

## Other responses

- `400`: Request was not successful
- `404`: Resource not found
- `409`: Conflict
- `422`: Invalid request parameters

## Changes

- **2026-10-23** (2025-11-10) `a490313abffa`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/clerk/apis/clerk-backend-api/changes/users/:user_id/merge/post.md)

---

[API](https://skmtc.dev/clerk/apis/clerk-backend-api.md) - [All operations](https://skmtc.dev/clerk/apis/clerk-backend-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clerk/apis/clerk-backend-api/revisions/a490313abffa?raw)