The Definitive Guide to Migrating to HubSpot

HubSpot, Inc. was founded by Brian Halligan and Dharmesh Shah in 2006 and is headquartered in Cambridge, Massachusetts ¹. Sales Hub is the sales-side product inside a broader suite that also includes Marketing Hub, Service Hub, Content Hub and Data Hub, all sharing the same underlying CRM.

The typical Sales Hub customer is a mid-market revenue team — 25 to 500 reps — that wants pipeline, sequences and reporting wired to inbound marketing without standing up a Salesforce-style admin function. Compared with Salesforce Sales Cloud, HubSpot positions itself on faster time-to-value and a flatter learning curve; compared with Pipedrive or Zoho, it positions on a deeper Marketing/Service overlay and a Custom Objects model that scales further on Enterprise tiers.

The shapes of migration that actually land on HubSpot tend to fall into four patterns. First, consolidation projects: a company replacing a stack of Pipedrive plus Mailchimp plus a Zendesk-style inbox with HubSpot's combined Smart CRM. Second, Salesforce exits, driven by total cost of ownership on smaller teams that never used Apex or flows heavily ²⁶.

Third, legacy replacements — Act!, SugarCRM, Microsoft Dynamics on-prem, or homegrown databases — where the source schema is loose and the project is really a re-architecture. Fourth, M&A integration, where an acquired business runs on a different CRM and the parent standardises on HubSpot. Each shape has a different difficulty profile: a Pipedrive migration usually has clean object parity but messy custom-field labels, while a Salesforce migration has rich automation that does not move across at all.

What makes migrating *to* HubSpot easier than the category average is the import tool itself — it accepts CSV and Excel, handles multi-object files via cross-reference columns, and has tier-scaled file and row limits that go up to 512 MB and 10 million rows per day on paid plans ².

What makes it harder than the average is the contacts-based pricing model, which can punish teams that bring in stale lists or fail to set marketing-versus-non-marketing status correctly during the load ²⁶, and the picklist (enumeration) value architecture, which uses internal values that diverge from display labels and will silently swallow any mismatch.

Workflows, sequences, reports and lead-scoring rules do not import — they are rebuilt from documentation. Teams that scope for that work up front finish on time; teams that assume parity do not.

Teams that scope for the rebuild work up front finish on time; teams that assume parity do not.

HubSpot's CRM is built around a small set of standard objects, each with default and custom properties, and associations that connect them. Sales Hub adds object access and pipeline behaviour on top of the same shared schema used by Marketing and Service Hubs.

Before you can map a field on the source side, you need to know exactly which destination object the row belongs on, what properties it requires, and which value will serve as its upsert key. The table below summarises the objects you will touch in a Sales Hub migration.

Contacts use email as the default unique identifier — two rows with the same email collapse into one record on import ². Companies use company domain name as their default unique identifier.

Deals, Tickets and Custom Objects do not have a natural unique key, so you should plan to either let HubSpot assign Record IDs and store them back in the source, or create a custom property of type single-line text, mark it Require unique values for this property, and use it as your external ID.

Once a property is created, you cannot retroactively make it unique — you create a new property with the unique setting on and copy values into it via a workflow. Plan for this on day one of the project.

When you import, HubSpot upserts on the unique identifier column: if a matching record exists, it updates; if not, it creates. You can also import the HubSpot Record ID as the match key when re-importing your own export — Record ID is the canonical primary key and bypasses email/domain matching entirely. Custom property types determine validation and storage; the catalogue below covers what you can model and the limits you need to plan around.

Relationships in HubSpot are modelled as associations with optional association labels (for example, a contact labelled *Decision Maker* on a deal) ⁹. Associations support cardinality limits per association type — HubSpot recently lifted the per-record association cap from 10,000 to 50,000 in most cases, but high-volume B2C wholesale scenarios still bump that ceiling and require splitting ¹⁰.

Custom Objects (Enterprise) participate in associations the same way standard objects do, including the same upsert and label semantics. There is no native master-detail cascade-delete: deleting a parent does not delete children, which is a behaviour you need to reproduce in workflows if your source platform relied on it.

The single best predictor of a clean Sales Hub migration is how much work you do on the source side before the first import button is pressed. HubSpot publishes its own warning that more than half of CRM data quality issues trace to the initial import, and the fix is almost always pre-processing rather than post-cleanup.

The single best predictor of a clean migration is how much work you do before the first import button is pressed.

Treat the source export as raw material that needs to be shaped to HubSpot's expected formats — email lowercased, phone normalised to E.164, picklist values converted to HubSpot internal values, dates rewritten to ISO-8601, owners resolved to HubSpot user IDs or emails.

Source-side prep

• Audit and dedup the source database before export — third-party tools like Insycle and Koalify are built specifically for HubSpot-bound dedup and can find email-case-only duplicates that HubSpot's importer will silently merge.
• Normalise emails to lowercase, trim whitespace, and strip role-based addresses (info@, sales@) that you do not want flooding marketing contacts. HubSpot lowercases on import but matches before you can intervene.
• Convert picklist display labels to HubSpot internal values for every enumeration field — lifecycle stage, deal stage, lead status, custom dropdowns. HubSpot rejects display labels silently on programmatic loads and partially against the UI.
• Stamp a stable external ID on every record in the source export — a UUID or the source platform's primary key — so re-runs and reconciliation are deterministic.
• Decide what is in scope for historical activities. Calls, emails, meetings, notes and tasks can be imported with a backdated *Activity Date*, but each row costs an activity create call and counts against daily import limits ².

Destination-side prep

• Create a sandbox from Settings → Account Management → Sandboxes (Enterprise) or use a standard development account on lower tiers. A sandbox is a full copy of production used to dry-run the import end-to-end.
• Provision users first, ideally with automated provisioning through Okta, Microsoft Entra ID or another identity provider, and create permission sets before importing — owner assignment fails silently if a referenced owner does not exist in HubSpot ¹³.
• Pre-create every custom property on the right object with the right type — single-line text vs multi-line text vs single-select matters because HubSpot will not let you change a created property's type later for many combinations.
• Build pipelines and deal stages before importing any deals — HubSpot rejects deal rows whose *Deal Stage* internal value does not exist on the specified pipeline.
• Define Custom Objects, their unique-ID properties, and their associations before importing. Custom Object schemas have to exist before records of that type can be created.

People prep

Cutover only works if humans cooperate. Lock down a source-system freeze window — typically 24 to 72 hours — and communicate it to every department that touches the CRM. Train sales reps on HubSpot daily-workflow tasks, deal management and pipeline reporting before go-live, not after. A typical small-business migration runs one to two business days; a complex multi-pipeline, multi-team migration runs two to four weeks of elapsed time even when the technical work is faster. Build the human runway accordingly.

HubSpot exposes several load paths and the right one depends on dataset size, object mix, and whether you need to re-run idempotently. The UI Import Tool covers most one-shot migrations under a few hundred thousand records. Programmatic loads handle large, repeatable volumes. Third-party tools sit on top of both and add staging, transformation and dedup layers.

UI Import Tool

The native import lives at Settings → Data Management → Data Integration → Import, or by clicking Import in the top right of any object index page. There are two modes: Quick Import for a single object with auto-mapped property names, and Advanced Import for full mapping control, multi-object files, and association creation. Quick Import requires one of *First Name*, *Last Name*, or *Email* in the file. Advanced Import accepts CSV, XLS and XLSX.

Limits are tier-scaled: free accounts get 20 MB files, 50 imports/day and 500,000 rows/day; Starter, Professional and Enterprise accounts get 512 MB files, 500 imports/day, 10,000,000 rows/day, and up to 1,048,576 rows per individual file ². Up to three imports run simultaneously, and only two can exceed 10,000 rows ². The right call: UI for one-shot loads under 100k records on standard objects, or any time you want a visual mapping review before commit.

Programmatic CRM imports and batch operations

There are two programmatic patterns. The Imports surface takes a metadata payload plus a file upload and runs the same engine as the UI — same mapping model, same daily limits, except programmatic imports can push up to 80,000,000 rows/day on paid tiers ²⁵.

The second pattern is per-object batch operations: create, update, and upsert. Batch calls accept up to 100 records per call for most objects, but contacts are limited to 10 records per call for create and update ¹⁴. Batch upsert requires the request to specify which property is the unique identifier; missing that property returns Updates in a single batch must specify its unique property. ¹⁶.

The platform-wide throughput ceiling on paid Marketing/CMS/Sales/Service Hubs is roughly 100 operations per 10 seconds on private-app tokens; respect the throttle response headers and back off on too-many-requests responses ¹⁵. Choose the programmatic path when the load is over 100k records, when Custom Objects are involved, or when the migration needs to be repeatable and audit-logged from your side.

Third-party staging tools

Tools like Fivetran, Airbyte, Stitch, Integrate.io and Workato sit between the source and HubSpot. They are commonly used in two ways: (a) reverse-ETL where the source database is loaded into a warehouse, transformed in SQL, then synced into HubSpot programmatically; and (b) staging-and-validate, where the tool handles file generation, type coercion and dedup before the result is fed to HubSpot.

For one-time migrations, the value is in repeatability under failure; for ongoing syncs (the post-migration phase), they become the system of integration.

Mapping is where every migration earns its scars. The schema decisions you make in your mapping spreadsheet determine whether reports work on day two, whether automations fire correctly on day five, and whether your sales team trusts the data on day thirty.

Work object by object, top to bottom of the import order: Companies first (so deals and contacts can associate to them), then Contacts, then Deals, then Activities, then Custom Objects and Line Items.

Contacts

Companies

Deals and pipelines

Recreate every pipeline and every deal stage in HubSpot before importing deals. Each deal stage has an internal value (often appointmentscheduled, qualifiedtobuy, closedwon, closedlost) and a numeric *probability*. Build the mapping table source-stage → HubSpot-pipeline + HubSpot-stage-internal-value. Deals that target a non-existent stage on the named pipeline are rejected with INVALID_DEAL_STAGE.

If you are consolidating multiple source pipelines, the cleanest approach is to keep them as separate HubSpot pipelines for at least 90 days post-migration, then merge once reporting has stabilised.

Custom-field mapping strategy

Resist the urge to map every source custom field one-to-one. Migrate only the custom properties used by an active process or report in the last 12 months. Excess properties weaken governance, slow down workflows, and make Breeze AI and HubSpot's reporting less effective.

For picklist fields whose source values do not match the destination, either: (1) extend the destination picklist with the missing internal values, (2) collapse adjacent values during transform, or (3) introduce a parallel custom property that holds the legacy value verbatim. Calculation properties (formulas) do not import — HubSpot recomputes them on-platform — so any source formula must be rebuilt as a HubSpot calculation property on Enterprise or replicated via workflow on lower tiers.

Historical activities — emails, calls, meetings, notes, tasks

HubSpot supports importing activities with their original timestamps via the *Activity Date* property — this is the field that determines where the engagement appears on the contact timeline ²³. For Gmail-resident historical email, HubSpot ships a dedicated *Historical email import* onboarding tool that pulls threads from Gmail and attaches them to the matching contact.

For calls and meetings logged in a source CRM, build a multi-object import where each row carries the activity body, owner, *Activity Date*, *Activity Type*, and the contact email/Record ID it associates with. Meetings additionally require an owner column mapped to *Activity assigned to* or the row is rejected. Email body fields will accept HTML; rich-text formatting from sources like Outlook may need to be converted to plain text first to avoid display issues.

Files and attachments

Attachments do not import in bulk via the CSV UI flow. The supported path is the Files surface, which uploads a binary and returns a file ID that can then be attached to a Note and associated with the parent record ¹⁸. Individual document size cap is 250 MB for trackable documents ¹⁸; one-to-one email attachments are capped at around 20 MB.

Plan for storage tier consumption — Files counts against the account's overall file storage allowance, which is tier-dependent. For large attachment estates (hundreds of GB), the pattern most teams adopt is: keep originals in S3 or Google Drive, store a deep link in a custom URL property on the HubSpot record, and only inline-upload the most recent or most-referenced subset.

Audit trail, ownership and original timestamps

Standard createdate, hs_object_id, hs_createdate and hs_lastmodifieddate are HubSpot-managed system properties — they cannot be overwritten during import ³. If you need to preserve the original audit trail, the pattern is to create two custom properties per object, *Legacy Created Date* and *Legacy Created By*, and populate them from the source export.

Owner assignment during import works only if the owner email or HubSpot user ID exists at the moment of import; rows whose owner cannot be resolved are imported with no owner set, which silently breaks downstream owner-based workflows.

Account-level activity audit logging is Enterprise-only ²⁵ — lower tiers can see import-level history in Settings → Imports but not granular per-property change history.

CRM-specific: lead scoring, sequences, email/calendar sync

Lead-scoring models do not import — they are rebuilt in HubSpot's score property type, configurable in Settings → Properties → HubSpot Score. Plan to recreate the rule logic from your source platform documentation rather than trying to migrate accumulated score values; if you must preserve historical scores, put them in a *Legacy Lead Score* custom number property and leave the new HubSpot score to accrue forward.

Sequences (the cadence tool) do not have an import mechanism either — recreate the structure manually and re-enroll active prospects post-cutover.

Email and calendar sync (Gmail/Outlook) is set up per user under Settings → General → Email and Calendar *after* users are provisioned; do not enable it during the import window or you will get a flood of duplicate emails as the connector backfills against the same contacts you are loading.

Validation is the bridge between the import finishing and users being allowed in. HubSpot's own field engineers recommend a three-stage validation: a test load of 10 percent of records with stakeholder spot-checks, the full load with real-time monitoring of record counts and association integrity, and a 30-day post-migration data-quality audit. The most reliable signal is having department reps verify their own records — they know what right looks like better than any reconciliation script.

Build a reconciliation queries spreadsheet that compares source and destination on each of these counts. Anything outside a 0.5 percent variance gets investigated before users get login access.

• Total contacts imported vs source — minus deliberately excluded rows (role-based emails, bounced lists, opt-outs).
• Total companies imported vs source — checking that domain-based collapse did not over-merge.
• Total deals per pipeline per stage vs source, plus **sum of *amount* per pipeline** — a non-trivial dollar variance usually signals a stage-mapping error or a currency-precision drop.
• Total activities per type (calls, emails, meetings, notes, tasks) imported vs source — and a date-bucketed comparison to confirm Activity Date round-tripped.
• Associations per object type — count contact→company, contact→deal and company→deal associations and compare against the source-derived expected counts.
• Owner distribution — GROUP BY hubspot_owner_id and confirm no record landed unowned that should not have.
• Unique-identifier integrity — count distinct emails on contacts, distinct domains on companies; any duplicates indicate the dedup transform missed cases.

On top of reconciliation, run a manual spot-check protocol: pick 30 random records across objects and verify each field against the source UI. Pick five high-value deals and trace the full association graph — contact, company, line items, activities. If a non-trivial discrepancy shows up in three or more of the 30, halt the load, fix the root cause, and re-import the affected rows by Record ID.

HubSpot now ships Restore CRM Properties and Records, which captures the last 20 versions of every CRM property change (45 for contacts) and lets super admins undo changes from the last 14 days via Settings → Data Management → Backup and Restore ²⁴. This is the closest thing to a native undo, but it is not a bulk-rollback button — it works property-by-property.

The real rollback strategy remains: export everything to S3 before the import starts, stamp every imported row with an *Import Batch ID* custom property, and if catastrophe strikes, bulk-delete by that batch ID and re-import from the cleaned source.

Cutover sequencing: (1) source goes read-only and the team is notified; (2) final delta export captures everything that changed during the test-import window; (3) delta is imported; (4) reconciliation runs; (5) users get login access and a 48-hour hyper-care window with the migration lead on call; (6) source decommission is scheduled for 30 to 90 days out, never the same day.

The HubSpot Solutions Partner Program tiers Elite, Diamond, Platinum and Gold partners by certifications, customer count and revenue. For Sales Hub migrations specifically, partners with explicit Salesforce-to-HubSpot, Marketo-to-HubSpot or Pipedrive-to-HubSpot practices tend to ship cleaner than generalist implementation shops.

SmartBug Media (Elite), Hyperscayle (Platinum), Incremental (Platinum), TransFunnel and Integrate IQ are commonly named in the migration corner of the market and each offers fixed-scope migration packages alongside ongoing managed services. HubSpot also runs an in-house Onboarding service with a published fee of roughly $3,000–$7,000 depending on tier; some partners waive that fee in exchange for the implementation contract.

On the ETL and iPaaS side, Fivetran, Airbyte, Stitch, Integrate.io, Workato and MuleSoft all have HubSpot connectors. Their role in a migration is rarely the migration itself — it is the staging layer that lands source data into a warehouse, the transformation layer that converts picklist values and resolves owner IDs, and the ongoing-sync layer that takes over once the one-time migration is complete.

Airbyte and Fivetran are common picks for warehouse-first teams; Workato is common where the migration is bundled with workflow automation rebuilds.

Managed-migration cost ranges vary widely. A clean Pipedrive-to-HubSpot move of under 25,000 contacts with no historical activities and standard objects only often lands in the £2,500–£7,500 / $3,000–$10,000 range with a setup fee plus per-object pricing. A Salesforce-to-HubSpot project with deal history, custom objects, historical activities and Marketo decoupling typically runs $25,000–$120,000, with the upper end driven by record count, custom-field complexity, historical-data depth and the number of integrations that need rebuilding rather than re-pointed.

For teams that want to outsource the migration end-to-end, FlitStack specialises in HubSpot migrations and handles the field mapping, historical-data preservation, picklist internal-value conversion, and validation work described in Sections 5 and 7 of this guide. Pricing is fixed-fee, based on record count and source platform, with separate line items for Custom Objects and historical activity depth so the scope is transparent before signature.

This is one of several legitimate paths — the right choice for any given team depends on whether they want an Elite Partner, an in-house onboarding service, an iPaaS-first approach, or a specialist migration vendor. Explore FlitStack →