HubSpot Data Migration Checklist

A bad HubSpot data migration does not show up on day one. It shows up three months later, when your sales team is working from four hundred duplicate companies and nobody remembers why.

Most HubSpot migrations do not fail during the move. They fail quietly, later: a report that does not add up, a customer who gets called twice by two different reps who both think they own the account, a field that silently stopped filling in halfway through. By the time someone notices, the cost is not the migration anymore. It is every decision made on top of bad data since.

Fixing that after the fact costs far more than doing it right the first time. A clean migration is not a single button press. It is six steps in order: check what you have, decide where it goes, remove the duplicates, test on a small batch, move everything, then verify it actually holds up. Skip a step and the cost does not disappear, it moves downstream to whoever trusts the report next.

This checklist is the process I use before moving a single record into a live HubSpot account, built across projects that ranged from one spreadsheet to a four-source sync moving over two million records.

TL;DR

• A clean HubSpot migration has six steps: check, map, deduplicate, test, move, verify. Skipping any step moves the cleanup cost to after go-live.
• Remove duplicates before you move data in, not after. HubSpot's automatic matching only catches exact email or web address matches. Everything else needs a plan.
• Test on a small, realistic batch first. A hundred records surface the mistakes a full move would only reveal once it is too late to undo cheaply.
• HubSpot's built-in tools handle most standard moves. Custom record types and merging several sources usually need a developer.
• Budget real time for checking the work after. A migration is not done when the records are in. It is done when the data holds up in a report someone makes a decision from.

Table of contents

1. What this actually costs you if it goes wrong
2. The six-step migration checklist
3. Common mistakes that create the mess
4. For your engineer
5. FAQ

What this actually costs you if it goes wrong

You cannot fix what you have not counted. Before anything else, get a real number: how many records exist, how many required fields are actually filled in, and how many records look like obvious duplicates on a first pass.

This check usually takes a day or two and saves weeks later. It is also where you find the gap between what you assumed your data looked like and what it actually looks like: the export with three different date formats, the "Company Name" field that is sometimes a person's name, the five thousand contacts with no email address at all. Every one of those becomes a wrong report, a missed follow-up, or a rep working from the wrong information if it moves into HubSpot unchecked.

The six-step migration checklist

Step 1: Check your data

• Get a full count of records per record type from your current system
• Check how many required fields are actually filled in
• Flag obvious duplicate patterns (same email, same web address, same phone)
• Note fields with inconsistent formatting (dates, phone numbers, currency)
• Confirm who signs off on the final plan

Step 2: Decide where everything goes

• List every HubSpot record type you will move data into (contacts, companies, deals, custom objects)
• Match every field from your old system to a HubSpot field, or mark it as excluded
• Decide the field type for each new HubSpot field (text, number, dropdown, date)
• Confirm how records connect (which contact belongs to which company)
• Get written sign-off on the plan before anyone builds anything

Step 3: Remove duplicates

• Define what counts as a match (email for contacts, web address for companies, an ID for custom objects)
• Run a cleanup pass on the old data before the move, not after
• Decide the rule when two records conflict (most recent wins, most complete wins, a person reviews it)
• Write down the cases your matching rule will miss

Step 4: Test on a small batch

• Pick a batch that represents your real data, not only the easiest hundred records
• Move that batch into a HubSpot test area, not the live account
• Check every field against the original record, one by one
• Confirm the connections landed correctly (contact to company, deal to contact)
• Fix any mistakes and test again before moving everything

Step 5: Move everything

• Schedule the move outside business hours if it touches a live account your team uses
• Move data in batches, not one giant file, so mistakes are easier to isolate
• Watch for errors in real time as it runs
• Keep the original export untouched in case you need to undo anything

Step 6: Verify it holds up

• Compare final record counts against the numbers from Step 1
• Spot-check a sample of records against the original source
• Run HubSpot's data quality tools to catch formatting issues the move missed
• Rebuild or check any reports and automations that depend on the moved fields
• Get sign-off from the team that will actually use the data day to day

Common mistakes that create the mess

Moving everything because deleting felt risky. Old, unused, or clearly stale records carried into HubSpot become tomorrow's data quality problem. Decide what actually needs to move.

Deciding where a field goes without deciding who owns it. A field with no clear owner goes out of date within a quarter, because nobody feels responsible for keeping it accurate.

Skipping the test batch to save a day. That saved day costs a week once the full move reveals a mistake at scale instead of in a hundred-record sample.

Treating the migration as separate from the ongoing sync. If you are also setting up a live connection alongside the migration, read the HubSpot integration timeline and plan both together. A broader list of failure patterns is in common HubSpot integration mistakes.

For your engineer

The rest of this section is written for the person doing the technical work: your developer, your HubSpot admin, or whoever you bring in for the project.

Map objects and properties before touching a single record. Mapping is where most migrations quietly go wrong. It feels like a formality, so teams rush it, and then discover mid-move that "Status" meant five different things depending on which spreadsheet it came from. Every source field needs one of three outcomes: it maps to an existing HubSpot property, it maps to a new HubSpot property created first, or it is explicitly excluded. HubSpot's own guidance on formatting import files is worth reading closely, since file structure errors are one of the most common reasons a move gets rejected outright. If the target data model includes custom objects, read HubSpot's custom objects guide before finalizing the mapping.

Build the deduplication strategy first. HubSpot automatically deduplicates contacts by email and companies by domain, per HubSpot's guide to record deduplication. That default catches the obvious cases and misses everything else: contacts with no email, companies with multiple domains, records using a different identifier entirely. Define a matching key before import, not after. For most migrations that means an external ID carried over from the source system.

HubSpot's native import tools versus a custom migration. HubSpot's built-in import tool, covered in its guide to importing records for multiple objects, handles most standard-object migrations well: contacts, companies, deals, tickets, from a CSV or Excel file, with a visual field-mapping step. It reaches its limit in two situations: migrating into custom objects with complex association rules, and merging records from multiple source systems where the same customer needs reconciling across all of them before a single HubSpot record gets created. In both cases, a scripted migration using HubSpot's API gives more control than the native tool, particularly around batching writes to respect HubSpot's rate limits during a large import.

FAQ

How long does a HubSpot data migration take?

A standard migration with clean source data, using HubSpot's native import tools, typically takes one to three weeks including checking, mapping, testing, and verifying. A multi-source migration into custom objects runs longer. See how long a HubSpot integration takes for the fuller breakdown.

Can I migrate data into HubSpot without losing my existing records?

Yes, if you plan your deduplication strategy before moving data in. HubSpot's automatic matching on email and web address handles the obvious overlaps; anything beyond that needs an explicit matching rule defined in advance.

What file format does HubSpot require for imports?

CSV, XLSX, or XLS files, with specific formatting requirements for dates, multi-select fields, and record connections. Review HubSpot's import file guide before building your export.

Do I need a developer for a HubSpot data migration?

Not always. Standard-object migrations from a clean CSV usually work fine with HubSpot's native import tool and no code. Multi-source migrations, custom objects, or complex deduplication logic benefit from a developer, which is where that cost pays for itself.

Next steps

Treat the checklist as a sequence, not a menu. Every step you skip becomes a cleanup task with a deadline attached later, usually right when someone needs the data for a decision.

I hold several HubSpot Academy certifications, including Data Integrations, and have run migrations ranging from single-object CSV imports to the four-source, two-million-record Reevia project. Use the HubSpot integration cost calculator to get a rough budget number before you scope the work. If your data is messier than a checklist alone can fix, talk to me about your migration.