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

# Merge User Profiles

> API to merge two user profiles to resolve duplicate user records.

In SuprSend, you can merge duplicate user identities into a single `distinct_id` to consolidate user profiles, especially when users interact across different products or transition from anonymous to identified states. You can use it in following scenarios:

* If a user can log into multiple products (such as different apps or services within your platform) and has different identifiers across products which needs to be merged later.
* **Anonymous to Identified Transition**: Many platforms allow users to interact or explore the product anonymously before signing up. During this period, user actions are typically tracked under an anonymous ID. Once the user signs up or logs in, you can merge the anonymous profile into their newly created identifier. This preserves any data collected during the anonymous period and associates it with the user’s identified profile. You need to [create a user](https://docs.suprsend.com/reference/create-update-users) with the new identifier first before merging the profiles.

### How profile merge works?

When you merge two users, there's a primary user passed in your API path param and merge a secondary / old user passed as `from_user_id` in your payload. The primary `distinct_id` is retained after the merge and the `from_user_id` is deleted. The deletion process is permanent and `from_user_id` can't be recovered once deleted.


## OpenAPI

````yaml POST /v1/user/{distinct_id}/merge/
openapi: 3.1.1
info:
  title: SuprSend API
  description: APIs supported on suprsend platform
  version: 1.2.2
servers:
  - url: https://hub.suprsend.com
security:
  - sec0: []
  - BearerAuth: []
paths:
  /v1/user/{distinct_id}/merge/:
    post:
      summary: Merge User Profiles
      description: API to merge two user profiles to resolve duplicate user records.
      operationId: merge-users
      parameters:
        - name: distinct_id
          in: path
          description: Unique identifier of primary user
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                from_user_id:
                  type: string
                  description: >-
                    Unique identifier of secondary user whose profile needs to
                    be merged into primary user.
      responses:
        '201':
          description: 201 - Created
          content:
            application/json:
              examples:
                Result:
                  value:
                    distinct_id: _distinct_id_
                    properties: {}
                    created_at: '2025-04-04T21:37:36.712496+00:00'
                    updated_at: '2025-04-04T21:37:36.743167+00:00'
                    $inbox:
                      - value: 4nlPk4t4kurG5kChOELB8Q1LcDI9DHzHQ70st2E2C24
                        id_provider: suprsend
                        status: active
                        perma_status: active
              schema:
                type: object
                description: user object of the primary user after the merge.
        '404':
          description: 404 - Not Found
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: 404
                    message: >-
                      from_user_id: [distinct_id: 'secondary_user'] not found /
                      user [distinct_id: 'primary_user'] not found
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: HTTP status code indicating the error.
                    example: 404
                  message:
                    type: string
                    description: Description of the error.
                    example: 'user [distinct_id: ''user1''] not found'
      deprecated: false
      security:
        - BearerAuth: []
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: Authorization
      x-bearer-format: bearer
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where <token>
        is your auth token.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_Key
      description: >-
        Pass as `Bearer <API_KEY>`. Get API Key from SuprSend dashboard
        Developers -> API Keys section.

````