Primary ID Preservation for Merged Records

What is it?

When you merge two CRM records, HubSpot now preserves the primary record's ID as the surviving record ID; no new ID is generated. The secondary record's ID becomes a forward reference that resolves to the primary record ID.

Why does it matter?

Until now, HubSpot generated a brand-new record ID every time two records were merged, a behavior that created friction for anyone managing integrations or external data systems:

- Integrations that cached or referenced record IDs broke silently after every merge
- Webhook consumers received an unexpected "object created" event for what was conceptually the same record
- Teams storing HubSpot IDs in external systems had to manually chase down the new canonical ID after each merge

With this change, record IDs stay stable across merges. This allows integrations to keep working, merge events to appear correctly on the timeline, and HubSpot's behavior to match what you'd expect from any other CRM.

How does it work?

This change is automatic. HubSpot applies it at the portal level with no configuration, install step, or user action required. This change is not retroactive, it will only affect merges moving forward.

For in-product merges:

The merge experience itself is unchanged. Navigate to the record you want to keep (the primary record), open the Actions menu, select Merge, choose the record to merge in, and confirm.

After the merge:

- The page URL stays on the primary record's ID
- The merge event appears on that record's timeline in place, rather than on a new record
- Visiting the secondary record's URL automatically redirects to the primary record
- Field-override UI copy has been updated to clarify that the primary record's ID is the surviving one

For API and integration users:

- The merge endpoint now returns the primary record's ID as the canonical ID, rather than a newly generated one
- Lookups by the secondary record's old ID continue to resolve correctly via forward reference — existing integrations that follow merge chains will keep working without changes
- If your integration previously detected a merge by checking for a new canonical ID, update your logic to check mergedObjectIds on the merge event instead
- See the migration guide on the HubSpot developer portal for the exact code changes required

Note: If you use 3rd party integrations that rely on the old behavior, opting into this public beta may affect or possibly break the integration. Please reach out to your representative of any critical 3rd party integrations you use to ensure this change will not adversely affect functionality.