What This Update Actually Is
Before this update, every merge in HubSpot created a brand-new record ID. The two original IDs disappeared. A fresh one replaced them.
Now, the primary record's ID survives as the canonical ID. The secondary record's ID becomes a forward reference that resolves to the primary record's ID. Anything that calls the old secondary ID still gets routed to the correct record automatically.
There's no configuration step. No install. No toggle. HubSpot applies it at the portal level the moment a merge happens from here forward. It's not retroactive, so merges that already happened aren't affected.
Why HubSpot Shipped This
Duplicate records are a fact of life in any growing CRM. The humans managing your portal merge them constantly. But every merge used to carry a hidden cost.
Integrations that stored HubSpot record IDs in external systems broke silently. Webhook consumers received an "object created" event for what was really the same record moving through a merge. RevOps teams had to manually track down the new canonical ID, update their data warehouse, and patch every downstream system. Every single time.
That's not a small burden. In portals with frequent deduplication work, this pattern created a recurring ops tax. The underlying frustration was real: HubSpot generated a new ID for what every team member understood to be the same record. The behavior didn't match the intent.
This update aligns HubSpot's merge behavior with what every other modern CRM already does. Stable IDs. Predictable events. No manual cleanup.
How to Use It Step by Step
The in-product merge experience hasn't changed. Here's the full flow:
- Navigate to the record you want to keep. This becomes the primary record and its ID survives.
- Open the Actions menu in the upper right of the record.
- Select Merge, then choose the record you want to absorb (the secondary record).
- Confirm the merge. The page URL stays on the primary record's ID. The merge event appears on that record's timeline in place.
- Verify by visiting the secondary record's old URL. It automatically redirects to the primary record.
For API and integration teams, two specific actions apply:
- Update merge-detection logic to check mergedObjectIds on the merge event instead of watching for a new canonical ID. The old detection pattern no longer works.
- Review third-party integrations before staying in the public beta. HubSpot explicitly notes that integrations built on the old behavior could break. Contact your integration vendors to confirm compatibility.
- Check HubSpot's developer migration guide for the exact code changes your team needs to make.
What It Touches in Your HubSpot Strategy
This update looks like a backend fix. But it has real surface area across your entire RevOps stack.
Integrations are the most obvious impact area. If your team stores HubSpot contact, company, or deal IDs in a data warehouse, a Salesforce sync, or a custom integration, those IDs are now stable across merges. That's a meaningful reliability gain. If you're in the middle of a HubSpot-Salesforce sync setup, this change affects how merge events flow between systems.
If you're running HubSpot alongside Salesforce, we recently broke down what HubSpot's Salesforce sync rebuild means for your data layer. Stable record IDs on the HubSpot side make that integration significantly cleaner.
Key Takeaway
Record ID stability now means integrations that store HubSpot IDs externally don't need a cleanup job after every deduplication run. That's a direct reduction in ops overhead for any team doing regular CRM hygiene.
Webhooks are the second impact area. Webhook consumers used to receive an "object created" event when records merged. That event was misleading. It triggered downstream automations that assumed a new record existed. With this update, the merge event appears correctly on the timeline, and webhook payloads reflect reality.
Timeline and reporting also benefit. Merge events now appear in place on the primary record's activity timeline rather than on a ghost record. That makes auditing a record's history cleaner and more accurate for any team reviewing activity before a sales call or support handoff.
Pair this with the reverse sort on the activity timeline that HubSpot recently shipped, and your records now have both cleaner merge history and flexible timeline navigation.
Key Takeaway
If your team uses HubSpot's API to build custom integrations, you need to update your merge-detection logic before this change ships to production. Check mergedObjectIds on merge events, not the presence of a new canonical ID.
Operations Hub users building custom workflows that trigger on record updates should review any enrollment triggers tied to contact or company creation. A merge no longer fires a "created" event, so workflows relying on that trigger won't fire incorrectly after a dedup run.
For ops leaders tracking API call volume, this update also reduces unnecessary API chatter caused by merge events generating new object lookups. If you're monitoring your API usage, check out HubSpot's consolidated subscription entitlements view to see your API call consumption in one place.
Who Should Care Most
Not every update moves the needle for every team. This one has a clear priority order.
- RevOps and operations managers who run regular deduplication workflows. This is your biggest quality-of-life improvement in the merge flow in years.
- Developers and integration engineers who maintain custom HubSpot integrations or consume the CRM API. You need to update your merge-detection logic now, before this becomes the default.
- Data and analytics teams who store HubSpot record IDs in a warehouse or BI tool. Stable IDs mean your foreign keys stay valid without a post-merge reconciliation job.
- Sales ops leaders managing high-volume prospecting portals where reps frequently merge duplicate contacts or companies.
- Any company using third-party integrations that touch the merge flow. These are the humans who need to move carefully. Audit your integration vendor's compatibility before relying on the beta behavior.
George's Take
I've audited a lot of HubSpot portals. One of the most common things I find is a quiet, festering problem: an integration that started returning bad data after a round of deduplication, and nobody noticed for weeks. The ops team merged some duplicate contacts, the external system got a "new record" event it didn't know what to do with, and suddenly a sales rep's dashboard was showing the wrong activity history. This update closes that loop. It sounds like plumbing because it is plumbing, and good plumbing is what keeps the whole house from flooding.
“The best CRM infrastructure is invisible. Stable IDs after a merge mean your integrations keep working, your timelines stay accurate, and your team doesn't have to be the humans who manually fix what the system should have handled automatically.”
If your portal has a Salesforce sync, a data warehouse connection, or any custom integration that touches CRM records, don't assume this change is zero-risk. Review it. One conversation with your integration vendor now saves a week of data forensics later.
Want a second set of eyes on how this update interacts with your integration stack? Book a strategy call with the Sidekick team. We'll walk through your portal, flag any merge-related risks, and make sure your integrations are set up to flourish with this change, not fight it.
Frequently Asked Questions
What happens to the secondary record's ID after a HubSpot merge?
The secondary record's ID becomes a forward reference that automatically resolves to the primary record's ID. Any API call or URL using the old secondary ID will redirect to the primary record. You don't need to update stored references to the secondary ID, but you should update any merge-detection logic that watched for a new canonical ID.
Is Primary ID Preservation automatic or do I need to configure it?
It's fully automatic. HubSpot applies it at the portal level with no configuration, install step, or user action required. All accounts in the public beta get it immediately. The change only affects merges going forward; it's not retroactive, so previously merged records are unaffected.
Will this update break my existing HubSpot integrations?
It might, if your integration was built to detect merges by watching for a newly generated canonical ID. You'll need to update that logic to check the mergedObjectIds field on the merge event instead. HubSpot has published a migration guide on their developer portal. Third-party integrations that rely on old merge behavior should be verified with their vendors before you stay in the beta.
Does Primary ID Preservation apply to all HubSpot record types?
Yes. The update applies to all CRM record types across all hubs and all pricing tiers, including contacts, companies, deals, and tickets. There's no per-object configuration needed. The behavior is consistent across every merge you perform in HubSpot going forward.
How do I find the migration guide for integrations affected by this change?
HubSpot's developer portal contains the exact code changes required for integration teams. Navigate to developers.hubspot.com and search for the Primary ID Preservation migration guide. The guide covers how to update merge-detection logic and how to handle the mergedObjectIds field on merge events correctly.
Does this change affect how HubSpot reports merge events on the activity timeline?
Yes, positively. Merge events now appear on the primary record's timeline in place rather than being associated with a new record. This means your activity history is accurate and continuous. The URL stays on the primary record's ID, and visiting the old secondary URL automatically redirects to the correct record.
