Migration or integration? Why most HubSpot implementations are migrations first

A migration moves history once. It has an end. Success is a reconciliation: the counts on both sides agree, the associations are wired, and the old system can be switched off.

An integration keeps two systems agreeing over time. It has no end. Success is what happens on a bad night: a watermark that held instead of advancing past a window it never read, a replay that resumed from a checkpoint, an association that queued for repair rather than vanishing into a log line.

They fail differently too. A migration that goes wrong is loud and immediate, and you find out during reconciliation. An integration that goes wrong is quiet. It drifts, and somebody notices weeks later that a report is short.

Ask whether anyone will change a record in the source system after go live.

If the answer is no, because the source is being retired or frozen, it is a migration. Build a loader, run it, reconcile it, delete it. There is no service to host, no scheduler and nothing to monitor, and any money spent on those is wasted.

If the answer is yes, because both systems stay in service and both keep changing records, it is an integration, and the approach guide covers which kind.

Most projects answer yes, and that is exactly why the migration comes first. An integration has nothing to attach to until the records exist in HubSpot and carry the keys the sync will match on. Every integration we have built opened with a backfill, which is a migration wearing a different name. A managed sync for a manufacturer opened by loading 20,004 orders reaching back to July 2020. Doing that backfill on the same keys the ongoing sync uses is the difference between one dataset and two.

The pattern is the same whatever the source, and none of it happens in a spreadsheet.

Properties first. Create the custom HubSpot properties that hold each object’s source identifier and let HubSpot enforce them as unique. Stamp a source system and a migration batch onto every record, which makes the cohort queryable later and makes a rollback a query rather than an archaeology exercise.

Then clean in code, not by hand. Phone formats, date sentinels, country spellings and split email cells are transform rules that have to run the same way on the sandbox load and the production load, six weeks apart.

Then upsert object by object in parent first order, keyed on the source identifier, on HubSpot API version 2026-03. Companies before contacts, contacts before the activity that hangs off them. Never key on an email address.

Then build associations in a pass of their own, from identifiers resolved out of the load responses rather than guessed. Then reconcile, before the next phase starts. Then run the whole thing twice in a sandbox, because a second run that updates in place and creates no duplicates is the only proof that the load is idempotent.

Cutover is a token swap. The same code, pointed at production, behind a portal allowlist that fails the run closed when the connected portal is not the one the environment expects. That sequence is the same one we run on every integration, set out in how we scope an integration.

Two routes look cheaper and are not, and we rule both out on real migrations.

The no code importer in HubSpot caps a job at about two objects. A four object load with six association types becomes a chain of manual, click driven imports that nobody can repeat for a sandbox and then again for production. Repeatable is the whole point.

The CSV Imports API can do the whole thing in one job, and it carries two costs that only show up afterwards. Records loaded that way are not filterable in lists, reports and workflows. Activities cannot be updated once created, which removes the fix path on a load nobody gets perfect the first time.

Both are fine for a one off list of contacts. Neither survives contact with a multi object migration that has to run twice.

A dual brand packaging distributor was retiring the sales layer sitting on top of its Pronto XI ERP, against a contract date rather than a preference. That layer holds no database of its own, so four exported files were the only snapshot that would ever exist.

The profile was 28,818 company records, 11,875 contacts after dedupe, 2,641 opportunities and 31,556 call records. The data closed the obvious route immediately: 5,036 contacts have no email address at all, and 416 email addresses are shared by 912 contacts. Email could not be the contact key. One fact made the rest workable, which is that referential integrity across the four files was clean, with no orphans on any foreign key, so a keyed load in parent first order would resolve every link.

A validation run settled five things the documentation had not. A company can carry a unique property, so no search then upsert workaround was needed. Calls cannot be upserted by any key, so the loader creates them and deduplicates against a map of source note ids read back from the portal. Call duration is stored in milliseconds, confirmed by writing a 60 minute call and reading back 3,600,000. The stage mapping lands on the right internal identifiers. And a second full run updates in place and creates no duplicates.

The full sandbox run reconciled exactly: 7,942 companies, 10,861 contacts, 3,598 deals and 26,006 calls, with the transform output matching the portal count on every object and zero failed records. Every contact, deal and call carried its company association, and 11,256 calls also reached a contact.

The load is smaller than the export on purpose. Account scope moved to an ERP first set days before the full run, web shop accounts were left out by agreement, and accounts with no purchase activity since 2020 were filtered out. That scope change is the honest lesson in the whole engagement: settle which accounts and which objects are in scope before mapping the entire export, not after. The full account is here, and the system page is sales-i and Pronto XI.

A four object keyed migration with an associations pass sits in the 70 to 150 hour build band, with 10 to 20 hours of discovery ahead of it. A single object load with no associations is closer to 40 to 60.

Keep one running when the source system survives go live and stays authoritative for something. A publisher’s backend stays authoritative for books, subscriptions and pricing while the sales desk works in HubSpot, so seven flows run on a schedule rather than one loader running once.

Do not keep one running out of nervousness. A sync against a system nobody edits any more is a service to patch, monitor and pay for, and it will eventually overwrite something a person fixed in HubSpot by hand. Retire the loader when the source is retired.

The work that carries from the migration into the sync is the valuable part: the object model, the match keys and the field mapping. Key every object on the source system’s own identifier at migration time and the integration becomes a scheduler over the same upsert logic, rather than a rebuild.