English

Exporting Cleanly from HubSpot: What the Native Export Misses

A RevOps team ran a textbook migration. Forty thousand contacts exported cleanly, companies matched up, deal stages mapped correctly. On day one in the new CRM, reps opened their deal records and found no contacts attached. Not a single deal-to-contact link had survived the migration.

The culprit was HubSpot's native export. It exports Contacts. It exports Companies. It exports Deals. But it doesn't export the associations between them. Those live in a separate data layer that the standard export tool doesn't touch. The sales team lost pipeline context on day one because nobody knew to ask about associations.

This guide covers everything the UI export leaves behind and how to get it before you migrate.

What HubSpot Data Looks Like Under the Hood

HubSpot organizes data into objects and associations. Understanding both is what separates a complete export from a broken one.

Objects:

  • Contacts — Individual people
  • Companies — Organizations (HubSpot's equivalent of Accounts)
  • Deals — Sales opportunities in a pipeline
  • Tickets — Support or service records
  • Custom objects — Anything your portal has built beyond the standard four

Associations are a separate data layer. A Contact can be associated with a Company, a Deal, and a Ticket simultaneously. But none of those links live inside the Contact record itself. They're stored in HubSpot's association graph. When you export a Contact to CSV, the associations don't come with it. The HubSpot CRM Associations API documentation explains the full association object model and how to retrieve relationship data programmatically.

Timeline events are the activity record. Every email sent, call logged, meeting booked, and form submission lives in a contact's timeline. These are also separate from the Contact record and require different export methods.

Knowing this architecture upfront tells you why a three-step export process is necessary, not optional. And it shapes how you approach field mapping between HubSpot and your destination system — associations are a separate mapping challenge from object properties.

Step 1: Native Export — What It Covers and Where to Use It

HubSpot's native export (Contacts > Export, Deals > Export, etc.) gives you flat CSVs of your object records. It's reliable for record counts and core properties. It's the right starting point.

What native export covers well:

  • All contact properties (standard and custom)
  • All company properties
  • All deal properties, including pipeline and stage
  • All ticket properties
  • Custom property values on any object

What to include in each export:

When HubSpot prompts you to select properties to export, don't accept the default selection. Choose "All properties" or manually select every property you want. Standard exports often omit custom properties unless you explicitly include them.

What native export does not cover:

  • Contact-to-Company associations
  • Contact-to-Deal associations
  • Deal-to-Company associations
  • Multi-object associations (a Deal associated with multiple Contacts)
  • Engagement records (calls, emails, meetings, notes)
  • Custom object records

Use native export to get your base record files. Then handle associations and engagement history separately. Before you start, confirm your scope with the guidance in preparing your data before you migrate anything — the decisions you make there determine which HubSpot properties actually matter.

Export method comparison:

Method Covers Misses Best for
Native UI export Contact/Company/Deal properties Associations, history Base record files
API (Associations endpoint) All association pairs Nothing — it's complete Association data
API (Engagements/Timeline) Calls, emails, meetings, notes Can't be exported via UI Activity history
Third-party tools (Coupler, Census) Multiple objects + associations Depends on tool config Teams without dev resources

Step 2: Export Associations Separately

HubSpot's association data requires either the API or a deliberate export setting. Here's both.

Option A: Use the Associations export within HubSpot

When exporting Contacts, look for an "Include associated records" option in the export dialog. In some portal versions, HubSpot lets you include associated Company name and Deal name in the Contact export. Check whether your portal version supports this. If it does, it saves an API call.

But note: "Including associated names" is not the same as exporting the full association graph. You'll get Company.Name and Deal.Name in the Contact row, but you won't get a proper many-to-many mapping of which Contacts are on which Deals.

Option B: Pull associations via the HubSpot API

The Associations API returns all association pairs for a given object type. A technical team member (or a RevOps person comfortable with API tools like Postman) can pull this programmatically.

The key endpoints:

  • GET /crm/v4/associations/contacts/companies/batch/read — Contact-to-Company pairs
  • GET /crm/v4/associations/contacts/deals/batch/read — Contact-to-Deal pairs
  • GET /crm/v4/associations/deals/companies/batch/read — Deal-to-Company pairs

Export these as separate files and treat them as join tables. In your destination CRM, you'll use these to re-establish relationships after importing base records.

If you don't have developer resources:

Tools like Coupler.io, Supermetrics, and HubSpot's own Data Sync feature can pull structured exports that include association data without API work. These are slower and sometimes cost extra, but they're genuinely useful for non-technical teams. Once you have the association data, testing the migration with a shadow import is how you verify the associations are intact before committing to the full move.

Step 3: Export Engagement and Activity History

HubSpot calls logged activity "engagements" and stores it in a timeline separate from the contact record. This data cannot be exported via the standard UI export. It requires the API.

What counts as engagement data:

  • Logged calls (with notes/outcome)
  • Logged emails
  • Meetings booked and completed
  • Notes added manually by reps
  • Tasks with completion data
  • Form submissions

What the timeline also contains (usually skip this):

  • Email open and click events (auto-logged by HubSpot tracking)
  • Page view events
  • Workflow enrollment history

The first category is rep-entered data — real sales context. The second category is system-generated event data. In most migrations, you want the first and should skip the second. Migrating hundreds of thousands of page view events creates noise in the destination CRM without any business value.

API endpoint:

GET /crm/v3/objects/engagements returns engagement records with their type (CALL, EMAIL, MEETING, NOTE, TASK), associated contact/company/deal IDs, and the engagement body content.

Practical workaround for non-technical teams:

If you can't access the API, document the decision explicitly: you're not migrating engagement history, and the source HubSpot portal will remain accessible in read-only mode for 90 days post-migration for anyone who needs historical context. A Forrester research report on CRM data migration notes that engagement history completeness is among the top five factors determining rep adoption velocity after a CRM switch. That's a legitimate business decision. Not every migration needs to carry full engagement history. The critical thing is making the call intentionally rather than discovering the gap after go-live. For everything you decide not to migrate, long-term archiving of legacy CRM data covers how to keep it accessible without paying full HubSpot licensing indefinitely.

Step 4: Handle Custom Objects

If your HubSpot portal has custom objects (common in portals that have been customized for specific industry workflows), those objects require their own export process.

How to check if your portal has custom objects:

Settings > Objects > Custom objects. If there's nothing here, skip this section.

Exporting custom objects:

Custom objects in HubSpot can't be exported via the standard UI export. Options:

  1. HubSpot API — Same pattern as standard objects. Use GET /crm/v3/objects/{customObjectType} with the custom object's internal name.
  2. HubSpot Data Sync — HubSpot's native sync tool can export to spreadsheets or databases, including custom objects.
  3. Third-party connectors — Tools like Airbyte or Fivetran have HubSpot connectors that handle custom objects natively.

For most teams without a dedicated data engineer, a third-party connector is the most reliable approach for custom object exports.

Step 5: Validate Completeness Before Leaving HubSpot

Don't start cleaning or importing until you've verified the export covers everything it should. A 30-minute validation now prevents weeks of reconciliation later.

Validation checklist:

  • Contact count in CSV matches HubSpot contact total (Settings > Account Defaults > Contacts)
  • Company count in CSV matches HubSpot company total
  • Deal count in CSV matches HubSpot deal total (check by pipeline if multiple pipelines exist)
  • Association export files exist for: Contact-Company, Contact-Deal, Deal-Company
  • Custom property definitions exported (Settings > Properties — export the property list separately)
  • Engagement export covers key types: calls, emails, meetings, notes
  • GDPR/opt-out fields included in Contact export (look for "Email opt-out", "Legal basis for processing", "GDPR consent" fields)
  • Lifecycle stage field included in Contact export

Sample association check:

Pick 10 Deals from your export. For each Deal, verify:

  1. The Contact IDs in your association file match contacts in your Contact export
  2. The Company IDs match companies in your Company export
  3. Count the number of Contacts per Deal — does it look right compared to HubSpot's UI?

Inconsistencies here mean your association export is incomplete. Fix it before cleaning.

Custom property completeness:

Export your property definitions (Settings > Properties > Download) and compare the property names to your CSV column headers. Missing columns indicate properties that weren't included in the export. Re-run with those properties added.

Common Pitfalls

Exporting contacts without companies. If Company records aren't in your export, every Contact loses its company association. Export Companies first, then Contacts with Company.Name included.

Losing lifecycle stage history. The Lifecycle Stage field updates over time, but HubSpot only stores the current value, not the history of when it changed. If lifecycle stage progression matters for your destination CRM setup, document the current state values at export time. You can't recover the history.

Missing custom property definitions. When you import into the destination CRM, you'll need to recreate all your custom properties. HubSpot lets you export the property definition list (not just the values). Download it — it'll save hours during field mapping.

Forgetting GDPR consent flags. If your portal tracks email consent or GDPR legal basis, those fields must be in your export. They're not in the default export columns. Add them explicitly. Losing consent records can create compliance problems in the destination system. The Wikipedia overview of GDPR covers the legal basis categories and right-to-erasure obligations that apply to CRM contact data.

Not accounting for deleted records. HubSpot doesn't have a recycle bin that's easily accessible via export. If you've deleted records that need to be in the migration, you'll need to work with HubSpot support or use the API's archived records endpoint.

What to Do Next

A validated HubSpot export means you have base record files plus association and engagement data. But none of it is import-ready yet.

The next step is data cleaning: deduplication, normalization, and enrichment. HubSpot orgs accumulate duplicates, inconsistent property values, and formatting issues over years of use. Clean before you import. According to Statista's CRM market data, over 91% of companies with more than 11 employees use CRM software — and the data quality challenges that accumulate in long-running CRM instances are consistent regardless of vendor.

If you're carrying engagement history forward, handling historical activities, notes, and emails covers the decision framework for what to actually migrate versus what to archive.

And if you haven't finished the pre-migration inventory, preparing your data before you migrate anything is where those decisions get made before export begins.

Learn More