How to Format and Clean a CSV for HubSpot Import: The Complete Guide

HubSpot Import Requirements by Object Type

HubSpot organizes data into objects: Contacts, Companies, Deals, and Tickets. Each object type has different required fields and different formatting rules. Before you clean your CSV, you need to know exactly which object you are importing and what HubSpot expects for each field.

For Contacts, the email address is the unique identifier. HubSpot uses email to determine whether a record is new or existing. If you import a contact with an email that already exists in HubSpot, the import will update the existing record rather than creating a new one. This is usually desirable, but it means your email data must be clean and consistent. A contact with "john@example.com" in HubSpot and "John@Example.com" in your CSV will correctly merge (HubSpot normalizes email casing), but "john@exmple.com" will create a duplicate.

For Companies, the company name or company domain serves as the identifier. HubSpot can associate contacts with companies based on email domain, so having clean company domain data is critical. For Deals, you need a deal name and an associated contact or company. For Tickets, you need a ticket name and pipeline stage.

HubSpot Field Format Requirements

The 250K Row Import Limit and How to Handle It

HubSpot limits individual CSV imports to 250,000 rows. If your dataset is larger than that, you need to split it into multiple files. This is not just a file size limitation; it is a per-import cap. Each file must be self-contained with its own header row.

When splitting large files, avoid breaking them arbitrarily. If your data contains related records, for example contacts at the same company, try to keep those records in the same file so that associations are created correctly during import. The best strategy is to sort by company domain before splitting, ensuring all contacts at the same organization land in the same import batch.

Also be aware that HubSpot's import processing time scales non-linearly with file size. A 10,000-row import might complete in under a minute, while a 250,000-row import can take 30 minutes or more. If you are doing a time-sensitive migration, plan accordingly and do not start the import 10 minutes before a meeting.

Common HubSpot Import Failures and Their Causes

1. Duplicate Contacts Created Instead of Updated

This is the single most common HubSpot import issue and it happens for one reason: the email address in your CSV does not match an existing contact. Typos, extra whitespace, different casing (though HubSpot handles this), or a missing email column entirely will cause HubSpot to create new contacts instead of updating existing ones. The downstream impact is severe: duplicate contacts confuse your sales team, corrupt your reporting, and can trigger duplicate marketing emails. Always validate and trim email addresses before import. NoSheet's email validator catches these issues automatically.

2. Date Parsing Errors Across the Entire Import

HubSpot strictly requires dates in YYYY-MM-DD (ISO 8601) format. If your CSV contains dates formatted as 03/15/2026, 15-Mar-2026, or March 15, 2026, HubSpot will reject the values for those fields. The insidious part is that the contact record will still import, but the date fields will be empty. This means your close dates, signup dates, and lifecycle timestamps will be blank, silently corrupting your pipeline reporting. Use the date standardizer to convert every date column to YYYY-MM-DD before uploading.

3. Lifecycle Stage Values Not Matching

HubSpot's lifecycle stages have specific internal values that must be used in CSV imports. The display name "Marketing Qualified Lead" does not work; the import value must be "marketingqualifiedlead" (one word, all lowercase). Similarly, "Sales Qualified Lead" must be "salesqualifiedlead", and "Opportunity" must be "opportunity". If your CSV uses abbreviations like "MQL" or "SQL", or uses the display names with spaces, the lifecycle stage field will import as blank, defaulting new contacts to "Subscriber" and potentially overwriting existing lifecycle stages on updates.

4. Phone Number Normalization Failures

HubSpot accepts phone numbers in various formats for display purposes, but if you plan to use HubSpot's calling features or integrate with telephony platforms, your numbers need to be in E.164 format. Numbers without country codes will default to the portal's country setting, which can produce incorrect international numbers. A UK number entered as 07700900000 in a US-based HubSpot portal will be interpreted as a US number. Always include the full E.164 format with the + prefix and country code.

5. Whitespace and Encoding Issues

Invisible whitespace is the silent killer of HubSpot imports. A trailing space in an email address creates a new contact instead of updating an existing one. Leading spaces in names appear in email personalization tokens, making your automated emails look broken. Non-breaking spaces (Unicode character 00A0) from copy-paste operations are invisible but cause matching failures across your entire CRM. Always trim all fields before import.

The Complete Pre-Import Cleaning Workflow

Follow this exact sequence before every HubSpot import to prevent the failures described above.

1. Trim whitespace from every cell. Remove leading, trailing, and double spaces from all fields. This single step prevents the majority of deduplication failures.
2. Validate and clean email addresses. Remove invalid addresses. Fix common domain typos. Ensure every contact has a valid email, since this is HubSpot's unique identifier.
3. Convert all dates to YYYY-MM-DD. This is non-negotiable. HubSpot will silently drop any date that does not match ISO 8601 format.
4. Format phone numbers to E.164. Add the + prefix and country code. Strip parentheses, dashes, dots, and spaces from the number itself.
5. Map lifecycle stages to internal values. Replace display names with HubSpot's internal enum values (subscriber, lead, marketingqualifiedlead, salesqualifiedlead, opportunity, customer, evangelist, other).
6. Deduplicate on email address. If your CSV contains duplicates, resolve them before import. Keep the most complete row or the most recent one, depending on your use case.
7. Remove unnecessary columns. Drop any column that does not map to a HubSpot property. Extra columns slow down the import and create mapping confusion.
8. Verify file size. If your CSV exceeds 250,000 rows, split it into multiple files with headers in each.

How NoSheet Automates HubSpot CSV Preparation

Every step in the workflow above maps to a NoSheet operation. Upload your CSV, run the operations in sequence, and download a file that is ready for HubSpot. Here is how each step works:

Email validation runs RFC-compliant checks on every row and flags addresses with common domain typos, missing @ symbols, and syntax errors. Date standardization detects the input format automatically, even when your CSV has mixed formats (some rows in MM/DD/YYYY, others in DD-MM-YYYY), and converts everything to YYYY-MM-DD. Phone formatting converts any input format to E.164 with a single click. Deduplication uses email as the match key and lets you configure which row to keep.

The entire workflow takes minutes, not hours. For a 50,000-row contact list, you can have a clean, HubSpot-ready CSV in under three minutes. NoSheet's Rust backend processes transformations at native speed, so even large files are handled without the lag you would experience in Google Sheets or Excel.

For more on preparing CRM imports, see our guides for Salesforce CSV cleaning and our comprehensive CSV data cleaning guide.

Related Resources