ACTION_ID: ackdb_merge_record
NAME: ackDB: Merge companies
CATEGORY: Integrations
CREDITS: 0

Fold one ackDB company into another — the same merge you run by ticking two
companies in Baseview, but driven by domains so a workflow can do it per
row. Name the primary company (the one that survives and keeps its ID) and
the secondary company (the one merged into it).

Everything moves off the secondary and onto the primary in a single
all-or-nothing step: identity links, traits, contacts, events, raw
payloads, content, files and conversations. Nothing is lost. Where the same
person held an active contact at both companies — one job split across two
duplicate records — the two contacts are folded into one rather than
leaving the person employed twice. The secondary company is then marked
merged and stops appearing anywhere.

⚠ THIS CANNOT BE UNDONE. There is no unmerge. Read §4 before wiring it to
anything that runs unattended.

PREREQUISITE: ackDB account connection — the user must create it in the Floqer UI
(Connections page); an agent cannot. Without it the action fails the row with
a connection / authentication error. Confirm it exists before configuring.

1. INPUTS

primary_company_survives_domain_or_entity_id (string, required)
  Primary company — survives (domain or entity ID). The company that WINS
  the merge: it keeps its ackDB entity ID and receives everything from the
  secondary company. Give its domain (e.g. acme.com), a full company URL
  (https://www.acme.com/about → acme.com), or its ackDB entity ID. The
  domain must match this company exactly — a near-miss is refused rather
  than merged.

secondary_company_merged_in_and_closed_domain_or_entity_id (string, required)
  Secondary company — merged in and closed (domain or entity ID). The
  duplicate company that is folded into the primary: its contacts, events,
  traits, identity links, content, files and conversations all move
  across, and the company itself is then marked merged and disappears from
  views. This is irreversible. Give its domain, a full company URL, or its
  ackDB entity ID. The domain must match this company exactly.

2. OUTPUTS

success (boolean) — True when the two companies are now one — either the
merge ran, or both inputs already pointed at the same company (nothing to
do). False when either company could not be matched exactly, or ackDB
rejected the merge — see `error`.
merged (boolean) — True only when a merge actually ran and the secondary
company was closed. False when both inputs were already the same company
(a no-op — `success` is still true), or when nothing was merged because of
a failure.
primary_found (boolean) — True when the primary company matched a real
company exactly. False means no company carries that domain, or the only
near match was a different company and was refused.
secondary_found (boolean) — True when the secondary company matched a real
company exactly, on the same terms as `primary_found`.
primary_entity_id (string) — The surviving company's ackDB entity ID — the
one to keep using from here. Blank when it wasn't found.
secondary_entity_id (string) — The merged-away company's former ackDB
entity ID. After a successful merge this ID is closed and points at the
primary. Blank when it wasn't found.
transferred (string) — JSON of what moved from the secondary company to
the primary: `{ linksTransferred, traitsTransferred, contactsTransferred,
contactsMerged, eventsTransferred, rawPayloadsTransferred,
contentTransferred, filesTransferred, conversationsTransferred }`.
`contactsMerged` counts people who existed at BOTH companies and were
folded into a single contact. All zero when no merge ran.
error (string) — Why nothing was merged: a company that couldn't be
matched exactly (naming the near-miss that was refused), or ackDB's
rejection of the merge. Blank on success.
message (string) — Human-readable summary of what happened.

3. HOW TO CONFIGURE

Configure Action body
(PATCH /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}):

{
  "inputs": {
    "primary_company_survives_domain_or_entity_id": "{{input.keep_domain}}",
    "secondary_company_merged_in_and_closed_domain_or_entity_id": "{{input.duplicate_domain}}"
  }
}

Field-by-field:
  - primary_...     Domain, full company URL, or ackDB entity ID of the
                    company that survives.
  - secondary_...   Same formats, for the company that is closed. Getting
                    these two the wrong way round is not recoverable.

4. KEY NOTES

- ⚠ There is no unmerge. Test on a throwaway pair first, and gate the
  action behind a `filter` so only rows you have actually reviewed reach
  it. On a wide sheet this runs per row, unattended, with no confirmation
  step.
- Which side is which matters permanently. The primary keeps its entity
  ID and every downstream reference to it; the secondary's ID is closed.
  Swapping the two inputs merges the wrong direction and cannot be undone.
- Exact-match is enforced deliberately. ackDB's company search is fuzzy
  and would otherwise hand back the closest company it can find — so a
  domain that isn't exactly that company's own is reported as not found,
  naming the near-miss it refused, and nothing is merged. Read `error` to
  see what was rejected.
- Both companies are checked before anything moves. If either is missing,
  nothing is sent to ackDB at all — there is no partial merge.
- `success` and `merged` answer different questions. Both inputs pointing
  at the same company gives `success: true, merged: false` — a no-op, not
  a failure. Branch on `merged` to count real merges, on `success` to
  catch problems.
- An entity ID is verified against ackDB too, so a stale or mistyped ID
  fails cleanly instead of merging the wrong record.
- `transferred` is a JSON *string*, not a json-typed field. Parse it in a
  `formula` before reading counts off it.

5. WHERE IT FITS IN A WORKFLOW

Pattern: duplicate detection (auto_dedupe_rows or a lookup that surfaces
two entity IDs for one company) -> formula (decide which domain survives)
-> filter (only reviewed rows) -> ackdb_merge_record.

6. WHEN TO USE

Use ackdb_merge_record when a de-duplication pass has produced pairs of
ackDB companies that are genuinely the same business, and you want the
merge done per row rather than by hand in Baseview.

7. WHEN NOT TO USE

You want to update a company rather than fold two together
  -> action-detail/ackdb_update_record.txt

You are looking a company or person up
  -> action-detail/ackdb_entity_lookup.txt

You want to send an event in
  -> action-detail/ackdb_ingest.txt

Last updated: 2026-08-13.