You just bought a list of 5,000 leads. Before you upload that file, know this: one wrong column can create thousands of duplicates or leave half your data missing.

HubSpot imports are unforgiving. A mismatched dropdown value gets skipped. A missing email creates a duplicate. A date formatted inconsistently throws errors on random rows.

The difference between a clean import and hours of cleanup comes down to how you set up your file before you hit upload.

Why Import Files Fail

Most import problems trace back to three mistakes:

Missing unique identifiers. Without an email address or Record ID, HubSpot cannot match incoming data to existing contacts. It creates new records instead, and you end up with duplicates.

Mismatched property values. Your file says "Sales Qualified" but your HubSpot property expects "SQL." HubSpot skips the value entirely, leaving the field blank.

Inconsistent formatting. Row 5 uses slashes for dates, row 50 uses dashes. HubSpot handles most formats, but inconsistency within a column causes unpredictable results.

Every one of these is preventable with proper file setup.

File Basics

Before you think about data, get the fundamentals right.

Accepted formats: Use .csv, .xlsx, or .xls
Single sheet only: If your Excel file has multiple tabs, HubSpot only reads the first one. Move all data to one sheet or split into multiple import files.
Every column needs a header: The first row must contain column names. HubSpot uses these to map data to properties. No header means the column gets ignored.
Maximum columns: 1,000 columns per file. If you hit this limit, you likely have data structure problems to solve before importing.

Required Columns for Contacts

At minimum, include at least one of: First name, Last name, or Email.

But here is what actually matters: Email is your unique identifier for contacts.

If the email in your file matches an existing contact in HubSpot, it updates that contact with any new data from your file.

If there is no email (and no Record ID), HubSpot cannot match to an existing record. It creates a new one. That is how duplicates happen.

For clean imports, always include email addresses. If you are importing contacts without emails, understand that you are creating records that cannot be deduplicated later without manual work.

Column Headers and Property Matching

Your column headers need to match properties that exist in HubSpot.

Before you import, check your properties: Settings → Properties

Look at the property names. Your column header should match either the property label (what you see in the UI) or the internal name (the API name).

During import, HubSpot shows you which columns it recognized automatically and which ones need manual mapping. That is your chance to catch mismatches before they become errors.

If a column does not map to any property, you have two choices: create a new property during import, or skip that column. Do not force a match to the wrong property just to get the data in.

Formatting by Field Type

Different property types require different formatting. Get this wrong and your values either get skipped or corrupted.

Dropdown, Radio, and Checkbox Fields

The value in your file must match either the option's label or its internal value. These are case-sensitive.

For HubSpot default properties (like Lifecycle stage), use the English label or the internal value. Even if your portal displays in another language, the import expects English or the internal value.

Check your property options in Settings → Properties before you build your file. Copy the exact spelling and capitalization.

Multiple Checkboxes

Separate values with semicolons, no spaces.

Example: value 1;value 2

If you add spaces after the semicolons, HubSpot may not recognize the values.

Date Fields

HubSpot accepts most date formats. All of these work:

10/28/2023
28-10-2023
2023.OCT.28

The key is consistency. Pick one format and use it across the entire column. If row 5 uses slashes and row 50 uses dashes, you are asking for trouble. HubSpot may interpret the formats differently and assign wrong dates.

Phone Numbers

Include the country code if you want HubSpot to format it automatically.

Example: +11234567890 ext123

Without the country code, HubSpot stores the number as-is but cannot validate or format it. For international contacts, always include the country code.

Single Checkbox (Boolean)

Use True or Yes for checked. Use False or No for unchecked.

Other values (1, 0, Y, N) may not work consistently. Stick with True/False or Yes/No.

Currency Fields

Format using decimals.

Example: 123.45

Do not include currency symbols, commas, or other formatting. Just the number with a decimal point for cents.

What Blank Cells Do

Blank cells do nothing. HubSpot skips them.

If a contact already has a value for a property and your import file has that cell blank, the existing value stays. Blank cells will not clear data, and they will not cause errors.

This is important to understand: imports add and update data. They do not delete data unless you specifically configure a workflow or use the API to clear values.

If you need to clear a property value across many contacts, an import is not the right tool. Use a workflow or bulk edit instead.

Technical Limits

Know your boundaries before you start.

Free accounts:

20MB maximum file size
500,000 rows per day
50 imports per day

Paid accounts:

512MB maximum file size
10,000,000 rows per day
500 imports per day

If your file exceeds these limits, split it into multiple files and import sequentially.

Frequently Asked Questions

What happens if my import creates duplicates?

HubSpot has a duplicate management tool under Contacts → Actions → Manage duplicates. You can review and merge duplicates there. But prevention is easier than cleanup. Always include email addresses and verify your data before importing.

Can I undo an import?

Not directly. HubSpot does not have a one-click undo for imports. You can delete the imported contacts if you filter by the import name (it creates a list automatically), but any data that updated existing contacts cannot be reverted without a backup.

Should I import to a list?

Yes. During import, HubSpot asks if you want to add contacts to a list. Always say yes. This gives you an easy way to find and manage the imported contacts later.

How do I update existing contacts without creating duplicates?

Include the email address in your file. HubSpot matches on email by default. If the email exists, it updates. If it does not, it creates. You can also match on Record ID for more precise control.

What if I need to import contacts and companies together?

HubSpot supports association imports. You can import contacts and companies in the same file and associate them during import. This requires specific column formatting. Check HubSpot's documentation for association import setup. Learn more at the HubSpot Knowledge Base: Set Up Your Import File.

Next Step

A clean import file takes fifteen minutes to set up correctly. A messy import creates hours of cleanup and data quality problems that compound over time.

But imports are just one piece of maintaining a healthy HubSpot database. If your CRM has become a dumping ground of inconsistent data, the import file is not the root cause.

We will audit your HubSpot data structure, identify where quality is breaking down, and give you a clear plan to fix it.

How to Set Up a HubSpot Contact Import File That Works