CRM Migration ID Mapping: Linking Old and New Records
You are mid-migration and the relationships will not rebuild. Without an old-to-new ID mapping table and a stable External ID on every object, you cannot reconnect Account-Contact-Opportunity links, validate row counts against source record IDs, or roll back cleanly when something fails.
We build the mapping layer before the first productive load.
Sound Familiar?
These are the exact issues programme leads hit when the migration key was treated as optional:
- Accounts, contacts, and opportunities loaded, but Account-Contact-Opportunity links cannot be rebuilt because nobody kept an old-to-new ID map
- Row counts match the source, yet validation against legacy record IDs is impossible without a migration key on every object
- A mid-migration retry created duplicates because there was no External ID upsert key to match on
- Rollback is a theory: HubSpot and most CRMs mint new IDs on create, so you cannot archive what you loaded without the mapping table
- Ops is VLOOKUP-matching emails by hand for weeks while sales works in a CRM that still cannot show who owns which deal
HubSpot will not preserve your source record IDs, and Salesforce assigns its own ID only at insert time. Practitioners treat an External ID strategy as one of the three factors that decide whether cutover weekend holds. If you are already loading without a map, every new batch makes relationships and rollback harder.
What the ID Mapping Layer Actually Does
Design the migration key → load with upserts → write the old-to-new map → validate and keep rollback possible.
Define External IDs
Unique migration key on every object before the first productive load
Upsert Parents First
Accounts and companies land keyed on External ID, not blind insert
Write the Lookup Table
Each batch records old ID → new ID so children and associations can resolve
Validate and Stay Ready
Reconcile to source IDs; keep the map for relationships and rollback
Everything You Need for a Reliable Record Mapping Spine
External ID and Migration Key Design
A unique, immutable External ID (or HubSpot unique property) on every migrated object before the first load. Source primary keys become the migration key that upserts and relationships depend on.
Old-to-New Lookup Tables
Per-batch record mapping of legacy ID to destination ID, written as each wave lands. That map is how you rebuild cross-object links, not a spreadsheet someone starts after cutover.
Upsert Keys, Not Blind Inserts
Retries and delta loads match on the External ID so a failed batch does not create a second copy of every account. Idempotent loads are the difference between a clean weekend and a duplicate crisis.
Cross-Object Link Preservation
Parents load first. Children reference parents by External ID or via the lookup table. Account hierarchies, contact roles, and deal associations resolve because the ID map exists before they need it.
Validation Against Source IDs
Row counts are not enough. We reconcile destination records back to source IDs so you can prove every migrated row, quarantine misses, and spot case-sensitive ID collisions before go-live.
Rollback-Ready Mapping Layer
Without the map you cannot programme a clean reverse. With it, you know exactly which destination IDs to archive or soft-delete when a trigger fires inside the rollback window.
Platforms We've Built ID Mapping For
From Three Weeks of Remapping to Four Days
How a 45-person B2B services firm stopped a mid-migration stall and rebuilt Account-Contact-Opportunity links once the ID map existed.
No Migration Key
- Salesforce to HubSpot load of ~58,000 contacts and ~11,000 deals with no External ID plan
- Row counts looked fine; associations did not resolve because source IDs were never stored
- Two ops leads spent three weeks VLOOKUP-matching emails to rebuild links by hand
- A retry wave created duplicates because nothing matched on a stable upsert key
- Rollback was impossible: nobody knew which HubSpot IDs the migration had created
ID Mapping Layer First
- Unique source_crm_id properties and Salesforce External IDs designed before the next wave
- Per-batch old-to-new lookup table written as each object landed
- Parents upserted first; children resolved via the map and External ID references
- Validation reconciled destination rows back to source IDs, not just totals
- Rollback script scoped to the map so a failed cutover had a reverse path
Before vs After an ID Mapping Strategy
How It Works
From first conversation to a proven mapping spine in 2 to 5 weeks, depending on object volume.
Key Strategy Workshop
Source systems, object graph, and which stable identifiers become External IDs. We design the migration key before anyone loads a row.
Scope and Quote
30-minute call on volume, platforms, and whether you are mid-migration without a map. Fixed scope for key design, lookup tables, and validation.
Build the Mapping Layer
External ID fields created, old-to-new tables wired per batch, upsert keys tested, parent-child loads sequenced against the map.
Validate and Cut Over
Reconcile against source IDs, prove associations, keep the map for rollback. First productive load only after the spine is proven.
Frequently Asked Questions
What is a CRM migration ID mapping strategy?
It is the plan that gives every record a stable link between the old system and the new one. Typically that means an External ID or unique migration key on each destination object, plus a persistent old-to-new lookup table written as loads complete. Without it you cannot rebuild relationships, run ID-level validation, or roll back cleanly, because destination CRMs mint new record IDs on create and will not preserve the ones you left behind.
Why can we not just match on email or company name?
Emails and names collide, change, and are not unique across objects. Salesforce IDs are case-sensitive; a published migration of roughly 80,000 contacts saw 35 genuine pairs collapse when a case-insensitive spreadsheet match treated different IDs as the same. External IDs and a proper record mapping table are deterministic. Fuzzy matching is a last resort for cleanup, not a migration spine.
Can HubSpot preserve our old record IDs?
No. HubSpot generates immutable new IDs on create, whether you are refreshing a sandbox or migrating from Salesforce. The recommended approach is a local mapping layer plus a custom unique property (for example source_crm_id) used as the upsert key. The same pattern applies on most modern CRMs: store the legacy ID, keep the old-to-new map, and never assume the destination will honour your source primary key.
What happens if we discover this mid-migration?
Stop blind inserts. Create External ID fields and unique properties before the next wave, export what already landed, build the missing old-to-new map for records already in the target, then resume with upserts keyed on the migration key. Teams that reverse parent-child order without a map routinely face thousands of orphaned deals and tens of thousands of contacts with no company hierarchy; rebuilding that by hand can take weeks. Industry guidance puts post-migration cleanup at roughly three to ten times the cost of fixing the key strategy before the move.
How does the ID map enable rollback?
Rollback needs to know which destination records the migration created. With a per-batch map you can archive or soft-delete exactly those IDs. Without it you are exporting everything, filtering by a migration stamp, and hoping the stamp is complete. HubSpot guidance typically keeps a 24 to 72 hour window where a clean reverse is still practical; after that, new work in the destination makes a tidy rollback much harder. The map is the recovery instrument.
How much does an ID mapping strategy as part of CRM migration cost?
Focused External ID design, lookup tables, and upsert wiring as part of a migration typically lands between R35,000 and R120,000 depending on object count and platform pair. Full remediations mid-migration, where relationships are already broken and duplicates exist, sit higher. Against weeks of hand remapping and published do-over costs in the R330,000 to R830,000 range for mid-market HubSpot rebuilds, most clients see payback inside the same quarter.
Stop Loading Without an ID Map
If your CRM migration cannot rebuild relationships, validate against source IDs, or roll back, the missing piece is almost always the old-to-new mapping layer.
Tell us which platforms you are moving between, how far the load has already gone, and whether Account-Contact-Opportunity links are already broken. We will show you how External IDs, upsert keys, and a persistent lookup table change the outcome.