---
title: "Merge two duplicate entities"
method: POST
path: "/api/v1/ackdb/entities/merge"
tags: ["ackDB"]
---

# Merge two duplicate entities

`POST /api/v1/ackdb/entities/merge`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/ackdb/entities/merge`
- Auth: HTTP bearer

Combines two entities into one using a winner/loser pattern. ALL data transfers from loser to winner: identity_links, traits, contacts, events, raw_payloads, entity_content, files, and conversations. No data is lost.

The loser entity is soft-deleted (status=merged, merged_into=winnerId).

Trait conflicts resolved by Postgres - winner's existing traits take precedence on key conflict. Identity link conflicts are handled automatically (loser's duplicate links are removed).

**Contacts (#325):** when the same PERSON has an active contact at BOTH companies, the two edges are the same affiliation split across duplicates — they are MERGED (events re-pointed, links/traits/ownership folded onto the surviving edge), reported as `contactsMerged`. Everything else is simply re-parented (`contactsTransferred`).

## Request body

- AckdbMergeRequest: Request to merge two duplicate entities. Winner keeps its entity_id.
  - `winnerId` string, required: Entity that survives the merge.
  - `loserId` string, required: Entity that gets soft-deleted after merge.

## Response `200`

Entities merged successfully

- AckdbMergeResponse: Response from a successful merge operation. All data is transferred - nothing is lost.
  - `data` object, required
    - `winnerId` string, required
    - `loserId` string, required
    - `linksTransferred` integer, required: Identity links moved to winner.
    - `traitsTransferred` integer, required: Traits re-assigned.
    - `contactsTransferred` integer, required: Contacts re-assigned.
    - `contactsMerged` integer, required: Loser contacts FOLDED into an existing winner contact because the same PERSON held an active edge at both companies (#325): one affiliation split across duplicate companies. Their events, links, traits and ownership move onto the surviving edge — nothing is dropped.
    - `eventsTransferred` integer, required: Entity events moved to winner.
    - `rawPayloadsTransferred` integer, required: Raw payloads moved to winner.
    - `contentTransferred` integer, required: Content chunks re-assigned.
    - `filesTransferred` integer, required: Files moved to winner.
    - `conversationsTransferred` integer, required: Conversations moved to winner.
    - `memberAssignmentsTransferred` integer, required: Member assignments moved or consolidated on the winner.
    - `relationshipsRepointed` integer, required
    - `relationshipDuplicatesConsolidated` integer, required
    - `selfRelationshipsRetracted` integer, required

## Other responses

- `404`: Entity not found
- `422`: Validation error

---

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