> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seam.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Merge User Identities

> Merges one or more [user identities](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) into a primary user identity, for when the same person ended up with more than one user identity.

The primary user identity takes on any email address or phone number it was missing from the user identities merged into it, and the merged user identities are then deleted. Their IDs and keys keep working: looking one up returns the primary user identity, and they are listed on it as `merged_user_identity_ids` and `merged_user_identity_keys`.

Access grants, access system users, client sessions and other resources belonging to the merged user identities are moved to the primary user identity.

Identify the user identities either by ID or by key, but not both in the same request. Repeating a merge that has already been applied makes no further changes.

You must include at least one request parameter.



## OpenAPI

````yaml /openapi.json post /user_identities/merge
openapi: 3.0.0
info:
  title: Seam Connect
  version: 1.0.0
servers:
  - url: https://connect.getseam.com
security: []
tags:
  - description: access_codes
    name: /access_codes
  - description: acs
    name: /acs
  - description: action_attempts
    name: /action_attempts
  - description: client_sessions
    name: /client_sessions
  - description: connected_accounts
    name: /connected_accounts
  - description: connect_webviews
    name: /connect_webviews
  - description: devices
    name: /devices
  - description: events
    name: /events
  - description: health
    name: /health
  - description: locks
    name: /locks
  - description: networks
    name: /networks
  - description: noise_sensors
    name: /noise_sensors
  - description: phones
    name: /phones
  - description: thermostats
    name: /thermostats
  - description: user_identities
    name: /user_identities
  - description: webhooks
    name: /webhooks
  - description: workspaces
    name: /workspaces
paths:
  /user_identities/merge:
    post:
      tags:
        - /user_identities
      summary: Merge User Identities
      description: >-
        Merges one or more [user
        identities](/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity)
        into a primary user identity, for when the same person ended up with
        more than one user identity.


        The primary user identity takes on any email address or phone number it
        was missing from the user identities merged into it, and the merged user
        identities are then deleted. Their IDs and keys keep working: looking
        one up returns the primary user identity, and they are listed on it as
        `merged_user_identity_ids` and `merged_user_identity_keys`.


        Access grants, access system users, client sessions and other resources
        belonging to the merged user identities are moved to the primary user
        identity.


        Identify the user identities either by ID or by key, but not both in the
        same request. Repeating a merge that has already been applied makes no
        further changes.


        You must include at least one request parameter.
      operationId: userIdentitiesMergePost
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - properties:
                    merged_user_identity_ids:
                      description: >-
                        IDs of the user identities to merge into the primary
                        user identity. These user identities are deleted.
                      items:
                        format: uuid
                        type: string
                      maxItems: 20
                      minItems: 1
                      type: array
                    user_identity_id:
                      description: ID of the primary user identity to keep.
                      format: uuid
                      type: string
                  required:
                    - user_identity_id
                    - merged_user_identity_ids
                  type: object
                - properties:
                    merged_user_identity_keys:
                      description: >-
                        Keys of the user identities to merge into the primary
                        user identity. These user identities are deleted.
                      items:
                        minLength: 1
                        type: string
                      maxItems: 20
                      minItems: 1
                      type: array
                    user_identity_key:
                      description: Key of the primary user identity to keep.
                      minLength: 1
                      type: string
                  required:
                    - user_identity_key
                    - merged_user_identity_keys
                  type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties: {}
                type: object
          description: OK
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      security:
        - api_key: []
        - pat_with_workspace: []
        - console_session_with_workspace: []
components:
  securitySchemes:
    api_key:
      bearerFormat: API Key
      scheme: bearer
      type: http
    pat_with_workspace:
      bearerFormat: API Token
      scheme: bearer
      type: http
    console_session_with_workspace:
      bearerFormat: Console Session Token
      scheme: bearer
      type: http

````