HubSpot Agency Migration Guide: Moving Client Data

Data migrations are where agencies earn their fee — or lose the client's confidence. Moving a client's CRM data into HubSpot (or between HubSpot portals) is one of the most common and most stressful projects an agency handles. Get it right, and the client starts with clean, well-organized data. Get it wrong, and you spend weeks fixing duplicates, missing associations, and broken workflows.

The difference between a smooth migration and a painful one almost always comes down to preparation. The actual data transfer is the easy part. The planning, mapping, cleaning, and validation around it is what determines the outcome.

This guide walks through the migration process from an agency perspective, with a focus on the practical decisions and common pitfalls.

Phase 1: Discovery and planning

Understand the source system

Before anything else, audit the source system thoroughly:

• What CRM are they coming from? Salesforce, Pipedrive, Zoho, a spreadsheet, or another HubSpot portal? Each source has its own export formats and data structures.
• How much data? Total record counts by object type — contacts, companies, deals, tickets, activities. This determines your migration approach and timeline.
• What's the data quality? Are there obvious problems (duplicates, incomplete records, inconsistent formatting) that should be fixed before or during migration?
• What are the critical fields? Which properties does the sales team actually use for daily work? Which ones are historical artifacts that nobody looks at?
• What associations exist? How are contacts linked to companies? How are deals associated with contacts? Preserving these relationships is often the trickiest part of a migration.

Map fields

Create a detailed field mapping document:

For dropdown and picklist fields, create a value mapping too:

This document is the single source of truth for the migration. Every decision about how data transforms from source to destination should be captured here.

Define what not to migrate

This is just as important as defining what to migrate. Common exclusions:

• Old, stale records. Contacts who haven't engaged in 3+ years may not be worth migrating. Discuss the cutoff with the client.
• Test data. Remove any test records from the source before export.
• Duplicate records. Deduplicate in the source system if possible, or plan for deduplication during import.
• Unused properties. If a field has data in less than 5% of records and nobody uses it, consider leaving it behind.

Getting client sign-off on exclusions before the migration prevents "where did my data go?" conversations afterward.

Phase 2: Prepare the destination

Set up the HubSpot portal

Before importing data, configure the destination portal:

1. Create custom properties for any source fields that don't map to HubSpot defaults. Match the property types carefully — importing text into a number field will fail silently.

2. Set up dropdown options for all picklist/dropdown properties. HubSpot will create new options on import if they don't exist, but they'll be in the order they're first encountered, not alphabetical or logical order.

3. Configure deal pipelines and stages to match the client's sales process. Importing deals with stage values that don't exist in any pipeline will cause mapping errors.

4. Disable workflows temporarily. If there are any active workflows in the destination portal, pause them before import. You don't want a migration triggering welcome emails to 10,000 historical contacts.

Prepare your import files

HubSpot imports use CSV files. Each import can handle one or two object types (for creating associations). Key rules:

• One CSV per object type for simple imports, or two related objects per CSV for association imports (e.g., contacts + companies)
• Required fields: Every object needs at least one unique identifier — email for contacts, domain for companies, a unique ID for deals
• Date formats: Use MM/DD/YYYY or YYYY-MM-DD. Inconsistent date formats in a single column will cause partial import failures.
• File size: HubSpot supports up to 512,000 rows per import file. For larger datasets, split the file.

Phase 3: Clean data before import

This is the step that separates professional migrations from amateur ones. Cleaning data before import is always faster than cleaning it after.

Common transformations

Phone number standardization. Source data will have phone numbers in every format imaginable. Standardize to one format before import using spreadsheet formulas or a data transformation tool.

Email validation. Remove obviously invalid emails (missing @ symbol, common typos like gmial.com). These will clutter your HubSpot contact list and hurt email deliverability.

Name formatting. Standardize capitalization (from JOHN SMITH or john smith to John Smith). Remove leading/trailing whitespace.

Company name cleanup. Standardize suffixes (Inc. vs Incorporated), remove special characters, and fix obvious misspellings.

Address standardization. Normalize country names, state abbreviations, and postal code formats.

Value mapping. Apply the value mappings from your field mapping document — converting source picklist values to HubSpot dropdown values.

If the dataset is large (50,000+ records), doing all this transformation in a spreadsheet becomes unwieldy. Consider using a scripting language or data transformation tool for complex mappings.

Phase 4: Execute the migration

Import order matters

Import objects in this order to maintain associations:

1. Companies — these are the parent objects for most associations
2. Contacts — associate with companies during import using company domain or name
3. Deals — associate with contacts and/or companies
4. Tickets — associate with contacts and/or companies
5. Custom objects — import after the objects they associate with
6. Activities (notes, tasks, calls) — associate with contacts, companies, or deals

Run a test import first

Before importing the full dataset, run a test with 50-100 records:

• Verify field mappings are correct
• Check that associations are created properly
• Confirm date formats parse correctly
• Verify dropdown values match existing options
• Check that no workflows were accidentally triggered

Fix any issues found in the test before proceeding with the full import.

Full import

Run the full import during off-hours if possible, and notify the client team that data will be loading. Monitor the import for errors — HubSpot will flag rows that failed and provide error details.

Phase 5: Post-migration cleanup

Even with careful preparation, post-migration cleanup is almost always necessary.

Validate record counts

Compare record counts in the source and destination. If you exported 15,000 contacts but only 14,200 imported, find out what happened to the other 800. Usually it's duplicates (HubSpot deduplicates by email), invalid records, or formatting errors.

Fix import artifacts

Common post-import issues:

• Encoding problems: Special characters (accents, em dashes, smart quotes) that were corrupted during CSV export/import
• Truncated values: Long text fields that exceeded HubSpot's character limits
• Missing associations: Records that didn't associate properly because the matching identifier wasn't found

Bulk data corrections

This is where a bulk search-and-replace tool becomes invaluable. Post-migration corrections often include:

• Fixing character encoding issues across thousands of records (replacing ’ with an apostrophe, for example)
• Correcting data that was imported with the wrong format
• Standardizing values that slipped through pre-import cleaning
• Updating references from the old system (like URLs or product names that changed)

A tool like SearchReplace lets you find these issues across all imported records and fix them in bulk, with a preview to make sure you're not creating new problems. This is especially useful for the encoding issues that are nearly impossible to catch completely before import.

Re-enable workflows

Once the data is clean, re-enable any workflows you paused. Review enrollment criteria to make sure historical records don't get enrolled in workflows meant for new records (use "contact creation date" filters to prevent this).

Post-migration validation checklist

Run through this checklist before declaring the migration complete:

• Record counts match expectations for each object type
• Sample records verified for data accuracy (spot-check 20-30 records)
• Associations between objects are correct
• Custom property values populated correctly
• Deal pipeline stages and amounts are accurate
• Activity history (notes, calls, emails) migrated and associated
• No workflows were accidentally triggered
• Search functionality works for migrated records
• Reports and dashboards show expected data
• Client team can find and work with their data

Communicating with the client

Throughout the migration, keep the client informed:

• Before: Share the field mapping and exclusion list for approval
• During: Notify them when the import starts and when it completes
• After: Provide a migration summary — what was migrated, any issues found, and the validation results

A clean migration is one of the strongest signals an agency can send about the quality of their work. It sets the foundation for everything that follows — reporting, automation, and the daily sales workflow all depend on the data being right.