Skip to main content
All Posts

HubSpot Contacts + Companies Import: Clean One-Sheet Files, Headers, IDs, and Domains

9 min readPipeSheets Team

When a HubSpot import of contacts and companies fails or half-loads, the cause is almost never HubSpot. It's the file. HubSpot needs one sheet per file, a header row where every column maps to a real property, UTF-8 encoding, and a unique identifier it can dedupe on: email for contacts, company domain name for companies. Get those four things right and records create, update, and associate cleanly. This guide covers the combined contacts-and-companies flow, including how to associate the two objects in a single file and the rejects that quietly skip rows.

If you only need the contacts-only error catalogue (invalid emails, mapping warnings, encoding), that's a separate topic. This post is about importing both objects and getting the dedupe and association mechanics to work.

What HubSpot requires from an import file

Before you map a single column, the file itself has to clear HubSpot's format rules. These apply whether you import contacts, companies, or both. The requirements below come straight from HubSpot's Knowledge Base article on formatting import files.

HubSpot's file-level requirements:

  • File type must be .csv, .xlsx, or .xls.
  • The file must contain only one sheet. A workbook with extra tabs (Sheet2, a pivot, a notes tab) is a common silent failure.
  • The first row must be a header row, and each column header should correspond to a property in HubSpot. Headers can be in any order.
  • Use UTF-8 encoding if the file contains foreign-language characters, otherwise accented names and non-Latin text arrive garbled.
  • The file must have fewer than 1,000 columns, and stay within the spreadsheet program's row and workbook limits.
  • To create a contact, each row needs at least one of First Name, Last Name, or Email.
  • To create a company, each row needs at least one of Name or Company domain name.

The one-sheet rule trips up more imports than any other. If you build your file in Excel with a working tab and a lookup tab, HubSpot may only read the first sheet or reject the file. Save a single-sheet copy specifically for the import.

Why headers have to match property names

During the mapping step, HubSpot tries to match each column header to an existing property. When a header matches exactly, it auto-maps. When it doesn't, you either map it by hand or the column gets left out and that data never lands. This is where inconsistent, human-friendly headers cause trouble: "Company", "Company Name", and "Account" are three different strings, and only one lines up with the standard property.

A clean header row that mirrors HubSpot's property labels lets the mapping screen do the work for you. Here's the difference between a messy export and an import-ready file.

Before (headers don't match properties, mixed case, stray spaces):

full name , E-mail Address ,Company , url ,Phone#
Jane Doe ,JANE@Acme.COM ,Acme Inc , Acme.com ,555-0100

After (headers map to standard HubSpot properties):

First Name,Last Name,Email,Company Name,Company domain name,Phone Number
Jane,Doe,jane@acme.com,Acme Inc,acme.com,555-0100

Notice the after version splits full name into First Name and Last Name, trims the whitespace around every value, and separates the visible company name from the machine-readable domain. That domain column is what makes the company half of the import deduplicate correctly.

Email and domain: the two dedupe keys that decide create vs. update

HubSpot deduplicates contacts by Email and companies by Company domain name. This is the single most important mechanic in a combined import, because it controls whether a row creates a brand-new record or updates an existing one:

How matching works during import:

  • Contacts are matched on the Email property. If an incoming email already exists, that contact is updated, not duplicated.
  • Companies are matched on the Company domain name property. Same domain in the file as an existing company means an update.
  • Record ID is HubSpot's own unique identifier. If your file includes a Record ID column exported from HubSpot, it takes priority as the match key and is the safest way to target updates.
  • To update existing records at all, your file must include one of these unique identifiers: Record ID, Email, or Company domain name.

The practical failure here is dirty keys. Two rows for the same person as jane@acme.com and Jane@Acme.com, or a domain written as https://www.acme.com in one row and acme.com in another, read as different records and create duplicates. Normalize both keys to lowercase, strip the protocol and www from domains, and trim surrounding whitespace before you import.

Domain values that fragment into duplicate companies:

Company domain name
https://www.acme.com/
Acme.com
  acme.com
www.acme.com

Normalized to a single dedupe key:

Company domain name
acme.com
acme.com
acme.com
acme.com

How to associate contacts to companies in one file

HubSpot lets you import multiple objects at once. In a single file, you associate two or more records per row by including the data for both objects in the same row, plus a unique identifier for each object. So one row carries the contact's details (email, name) and the company's details (name, domain), and HubSpot creates or updates both and links them.

The association hinges on the company domain name being present and clean on every row. Here's a one-file, two-object layout that associates each contact with their company in a single pass.

One file, two objects, associated by row:

First Name,Last Name,Email,Company Name,Company domain name
Jane,Doe,jane@acme.com,Acme Inc,acme.com
Sam,Lee,sam@acme.com,Acme Inc,acme.com
Ravi,Patel,ravi@globex.io,Globex,globex.io

Result: two contacts associated to the Acme Inc company
(deduped to one company on acme.com), one contact to Globex.

During mapping you tell HubSpot which columns belong to the contact object and which belong to the company object, and it associates them by row. If you prefer to keep contacts and companies in separate files, you can run a two-file import instead and pick a common column header shared by both files to link them. The single-file approach is usually simpler for a straightforward contact-to-company relationship.

HubSpot can also auto-associate contacts and companies by matching the domain in a contact's email to a company's Company domain name. That only works if both values are clean. jane@acme.com links to the company on acme.com; a contact stored under a personal Gmail or a domain with a typo won't associate.

Date and number formats that pass validation

Date properties are the most common reason a row imports but a value silently goes blank. HubSpot accepts date values in these formats: mm/dd/yyyy, dd/mm/yyyy, yyyy-mm-dd, or dd mm yyyy. In the import wizard's mapping step, a date column shows a check mark when it's recognized and an exclamation mark when it isn't; click the exclamation mark to select the format your data actually uses.

If the format you declare doesn't match the values in the cells, HubSpot returns COULD_NOT_PARSE_DATE with a message like "Can't process date using MDY format." The safest fix is to normalize every date column to yyyy-mm-dd (ISO) so there's no ambiguity between day and month, then confirm the wizard is set to match.

Ambiguous and mixed date formats that fail:

Create Date
3/4/2026
04-03-2026
March 4, 2026
2026/03/04

Normalized to ISO (yyyy-mm-dd), unambiguous:

Create Date
2026-03-04
2026-03-04
2026-03-04
2026-03-04

Number properties are stricter than they look. A revenue or employee-count column with text like "1,200", "$1200", or "~1200" can import as a warning instead of an error: the record loads but the numeric value doesn't write. Strip currency symbols, thousands separators, and stray characters so number columns contain only digits (and a decimal point where needed).

Common rejects and what they mean

After an import, HubSpot lets you download an error file that flags each problem row. There are two severities worth understanding, because they behave differently:

Error vs. warning in the results:

  • Error: the row was not imported. The usual cause is an invalid email address or a structural problem in the CSV. No record is created for that row.
  • Warning: the record imported, but a value wasn't written, for example a picklist value that doesn't match an existing option, or text sitting in a number field.
  • Invalid email: a malformed address (missing @, trailing spaces, a stray comma splitting the cell) rejects the contact and, in a combined import, can break the association for that row.
  • Malformed domain: a Company domain name with a protocol, path, or typo either fails to match or spawns a duplicate company.
  • Unknown or unmapped header: a column whose header matches no property and isn't mapped by hand is dropped, so that data never arrives.

Almost all of these trace back to the same root: values that look fine to a human but don't parse cleanly. A comma inside an unquoted field shifts every later column by one, so an email lands in the phone column and the row rejects. Leading zeros stripped from a postal code, smart quotes from a copy-paste, or a trailing space on a domain all read as bad data to the importer.

A pre-import cleanup checklist

Run through this before every contacts-and-companies import:

  • Save the file as a single sheet, .csv or .xlsx, UTF-8 encoded.
  • Make the header row match HubSpot property names (First Name, Last Name, Email, Company Name, Company domain name).
  • Trim leading and trailing whitespace from every cell, especially emails and domains.
  • Lowercase all email addresses so they dedupe as one contact.
  • Strip https://, www., paths, and trailing slashes from Company domain name so each domain is one clean key.
  • Split any single full-name column into First Name and Last Name.
  • Normalize date columns to yyyy-mm-dd and match the format in the wizard.
  • Remove currency symbols and thousands separators from number columns.
  • Confirm every row has a dedupe key: Email for contacts, Company domain name for companies, or a Record ID exported from HubSpot.
  • Delete fully empty rows and columns so blanks don't map to properties.

Cleaning the file without wrestling Excel

Most of this checklist is find-and-replace and column surgery, which is exactly what Excel does badly: it re-strips leading zeros, reformats dates on open, and mangles UTF-8. This is where a dedicated cleaning pass helps. PipeSheets lets you upload the export, run steps like trim whitespace, normalize headers, standardize nulls, and lowercase a column with case transform, then preview the before and after with detected column types before you download a clean CSV or XLSX. For domain and email normalization, its find-and-replace (including regex) strips protocols and www in one step.

The Quick Clean preset alone handles the boring baseline: it trims whitespace across all columns, standardizes null values, removes fully empty rows and columns, and normalizes headers. From there you save a custom pipeline that lowercases emails and cleans the domain column, and reuse it on every export so the file is import-ready without redoing the work each month. Because PipeSheets keeps leading zeros and dates intact, the values you send to HubSpot are the values that were actually in your source.

Clean keys are the whole game. When email and Company domain name are consistent, HubSpot deduplicates correctly, updates the right records, and associates each contact to the right company on the first import instead of leaving you to untangle duplicates afterward.

Related tools & guides

Try the automated solution

PipeSheets can fix these issues automatically. Clean your first file free.

Clean Your CSV