TL;DR: When you merge two records in HubSpot, you don't get a modified Record A — you get a brand-new record with a new ID. This is a change from how HubSpot merges used to work: earlier, the primary record's ID was preserved after a merge. Today, both originals are archived and a net-new ID is issued for the consolidated record. Every child object (Deals, Tickets, Activities, Custom Objects) from both records is automatically transferred. Old IDs are still routable via aliasing, but your integrations and workflows need explicit handling. Read on for the full architecture breakdown.
Duplicate records are the most common data quality problem in HubSpot. Every RevOps team hits it. A contact submits a form twice, a sales rep manually creates a company that already exists, or an integration sync creates a ghost record.
The fix is a merge — but a merge in HubSpot isn't a simple overwrite. It's an architectural event with consequences across your child objects, record IDs, active workflows, and any downstream system that maps to HubSpot IDs.
Whether your sales rep is clicking Merge in the UI or a developer is hitting the HubSpot CRM API merge endpoint, the same chain reaction fires underneath.
This guide breaks down exactly what happens, why it matters for your integrations, and how to design around it.
1. You Don't Control the Merge Logic — HubSpot Does
The first thing to accept: HubSpot's merge is fully automated and non-configurable.
There are no API flags or UI options to selectively merge some child objects and exclude others. The HubSpot Merge API payload accepts exactly two parameters:
{
"primaryObjectId": "111111",
"objectIdToMerge": "222222"
}
That's it. You designate a primary and a secondary — HubSpot does everything else.
Because the secondary record (objectIdToMerge) is permanently deleted, HubSpot guarantees data integrity by automatically sweeping every child object associated with it and reassigning it to the surviving consolidated record.
Why this matters for RevOps: If you need to split child objects before merging (e.g., keeping a Deal on the secondary company separate from the primary), you must use the HubSpot Associations API to reassociate or detach those objects before calling the merge endpoint. There is no post-merge undo.
2. The Domino Effect on Child Objects
When a merge fires, every connected child object — Deals, Tickets, Line Items, Activities, Custom Objects — shifts based on three rules:
Timelines Merge Chronologically
All activity history from both records is stitched into a single master timeline. Every note, logged email, recorded call, meeting, task, and system event is preserved and sorted chronologically. Nothing is dropped.
Associations Are Deduplicated
If Company A was associated with Contact 1, and Company B was associated with Contact 2, the merged record links to both Contact 1 and Contact 2.
If both records shared an association to the same child object, HubSpot flattens that into a single link — no duplicate references.
See HubSpot's association behavior documentation for the full rules on how labels are inherited during a merge.
Primary Label Hierarchy Is Enforced
HubSpot association labels let you mark a "Primary" company for a contact or deal. During a merge:
- Child objects from your designated
primaryObjectIdkeep their Primary label. - Child objects pulled from the
objectIdToMergerecord have their Primary label stripped — they remain linked, but lose priority status.
This prevents a contact from ending up with two "Primary" companies simultaneously.
3. The New Record ID: The Change That Breaks Integrations
This is the most operationally significant behavior, and the one most teams miss.
HubSpot merges do not preserve the primary record's ID. This is a behavior change from earlier versions of HubSpot, where the primary record's ID was retained after a merge. The current platform creates a brand-new consolidated record with a new ID, then archives both originals.
[Record A: ID 111111] ──┐
├──▶ [New Consolidated Record: ID 333333]
[Record B: ID 222222] ──┘
HubSpot's record merge documentation confirms this behavior. Here's what it means practically:
Implicit ID Forwarding (don't rely on it long-term)
HubSpot's API aliases old IDs to the new one. A read or write request using 111111 or 222222 routes to 333333 automatically. This feels safe — until you're debugging a stale ID six months later in your data warehouse.
hs_merged_object_ids Property (use this)
Every merged record carries this hidden HubSpot property containing an array of all predecessor IDs. Query it to build a reliable lineage map in your external system.
Workflow Unenrollment Both original records are immediately unenrolled from any active HubSpot workflow the moment the merge fires. The new record does not auto-enroll unless your workflow trigger explicitly allows re-enrollment on property changes or re-enrollment is configured.
4. Integration Developer Playbook
If you're mapping HubSpot to an ERP, data warehouse, or any external system that stores HubSpot record IDs, implicit ID forwarding is a liability — not a solution.
Before the Merge: Intercept Sensitive Child Objects
If specific Deals or Custom Object records must not follow the secondary record into the merge, detach them first using the Associations API:
DELETE /crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/{toObjectType}/{toObjectId}
Do this programmatically before calling the merge endpoint.
After the Merge: Listen to the Right Webhook
Standard propertyChange and deletion webhooks fire inconsistently during a merge — you cannot rely on them to catch it. Instead, subscribe explicitly to the crm.objects.merge webhook event in your HubSpot webhook subscription.
The payload gives you everything you need to update your external ID references:
{
"subscriptionType": "crm.objects.merge",
"portalId": 999999,
"primaryObjectId": 111111,
"mergedObjectIds": [222222],
"newObjectId": 333333,
"occurredAt": 1780000000000,
"changeSource": "CRM_UI"
}
Use newObjectId to immediately update the record identifier in your own database. This eliminates any dependency on HubSpot's aliasing layer.
The RevOps Checklist Before Running a Bulk Merge
Before merging records at scale — whether manually or via automation — run through this:
- Identify sensitive child objects — Are there Deals, Tickets, or Custom Object records on the secondary that should not follow it? Reassociate them first.
- Check active workflow enrollments — Which workflows are the records enrolled in? Both will be unenrolled post-merge. Plan for re-enrollment logic.
- Notify integration owners — Any system storing HubSpot record IDs needs to be updated. Share the new ID mapping.
- Subscribe to
crm.objects.mergewebhooks — If you haven't already, set this up before running bulk operations. - Query
hs_merged_object_idspost-merge — Validate the lineage is clean and stored externally.
Frequently Asked Questions
What happens to Deals when you merge two HubSpot companies? All Deals associated with the secondary company are automatically transferred to the merged (new) record. No Deals are deleted. The primary company's Deals retain their Primary association label; the secondary company's Deals retain the association but lose the Primary label.
Does merging HubSpot records delete the original record IDs?
Both original records are archived and a brand-new ID is issued for the consolidated record. Note that this is a change from how HubSpot used to behave — earlier versions retained the primary record's ID post-merge. Today, neither original ID survives as the canonical identifier. HubSpot's API aliases the old IDs to the new one, but you should not rely on this long-term — update your external systems using the crm.objects.merge webhook payload.
Can you undo a merge in HubSpot? No. HubSpot merges are irreversible through the UI or API. HubSpot's support documentation confirms there is no native undo. This is why pre-merge planning — especially for child objects and workflow enrollments — is critical.
What is hs_merged_object_ids in HubSpot?
It's a system property on every HubSpot object that stores an array of all predecessor record IDs that were merged into the current record. Use it to trace lineage and keep external databases in sync.
Do HubSpot workflows re-enroll after a merge? No. Both records are immediately unenrolled. The new record must meet a fresh trigger condition (if re-enrollment is enabled on the workflow) or be manually enrolled. Workflow re-enrollment behavior is documented in HubSpot's workflows knowledge base.
How do I merge records via the HubSpot API?
Use a POST request to /crm/v4/objects/{objectType}/{objectId}/merge with a body of {"primaryObjectId": "ID_A", "objectIdToMerge": "ID_B"}. Full details in HubSpot's CRM Merging Records API reference.
Summary
HubSpot's merge engine is designed to protect your data — nothing falls through the cracks. But the architectural reality is that a merge is not a modification of an existing record. It's the creation of a new one.
The teams that handle this well treat merges as events to be designed around: intercepting child objects before, subscribing to the right webhook after, and updating external systems proactively rather than relying on HubSpot's aliasing as a permanent crutch.
Running duplicate records at scale in HubSpot? CleanupCRM automates the identification, review, and safe merging of HubSpot duplicates — with full visibility into child object impact before the merge fires.