HubSpot's file rules
Fix mistakes in the import tool
When HubSpot reports incorrect or missing values, you can correct them in the import tool without uploading the file again. It's still worth fixing the source file, so the next import is clean.
Common errors and their fixes
Duplicate records after the import
Cause: HubSpot can only match rows to existing records by a unique identifier: Email for contacts, Company domain name for companies, or a Record ID. Without one, every row becomes a new record.
Fix: Include the identifier column and map it during the import. To update existing records, export them first so you have their Record IDs.
Dropdown values not imported
Cause: For dropdown, radio and other option properties, each value must match one of the property's options, by its label or its internal value. Customer vs customer, or an option that doesn't exist yet, won't match.
Fix: Use the exact option labels from the property settings, and create any missing options before importing. For default properties such as Lifecycle stage, use the internal value or the English label. See enforcing dropdowns in Excel to stop typos at the source.
Multiple checkbox values wrong
Cause: Several values in one cell must be separated by semicolons with no spaces. Commas, or spaces after the semicolons, don't split correctly.
Fix: Write them as Option A;Option B;Option C, and create every option on the property first.
Dates in the wrong month
Cause: HubSpot accepts day-month-year, month-day-year and year-month-day. A date like 03/04/2026 can be read either way, depending on the format chosen during the import.
Fix: Use YYYY-MM-DD where you can, and check the date format setting in the import. Dates without a time are set to midnight. More in the CSV date formatting guide.
Phone numbers without a country
Cause: HubSpot's format is +[country code][number], with an extension written as ext[number]. Numbers without a country code are ambiguous across countries.
Fix: Add the country code, such as +44 20 7946 0958. The phone numbers guide covers cleaning them in bulk.
Single checkbox values ignored
Cause: On/off properties expect True or Yes, False or No. Values like Y, 1 or X aren't recognised.
Fix: Use True/False or Yes/No in those columns.
Garbled characters (é becomes é)
Cause: HubSpot asks for UTF-8 when a file includes accented or non-English characters. Excel's plain CSV on Windows isn't UTF-8.
Fix: Save as CSV UTF-8 in Excel, or download the CSV from Google Sheets. See the special characters guide.
Columns left unmapped
Cause: Each column header should correspond to a HubSpot property. Headers HubSpot can't match are left for you to map by hand, and easy to skip.
Fix: Name headers after the property labels (First name, Email, Phone number), map anything left over, and create custom properties before importing.
Blank cells didn't clear existing values
Cause: The import ignores blank cells, so an empty cell never removes a value already in HubSpot.
Fix: That's by design. Clear values in HubSpot itself, for example with a bulk edit, rather than through the import.
Associations not created
Cause: When importing related records together, an association label in the file that doesn't exist in HubSpot, or one over the association limit, imports the records but not the link between them.
Fix: Create the association labels first and check the limits before importing.
How HubSpot expects values to be written
| Property type | Write it as |
|---|---|
| Date | 2026-03-04 (or day-month-year / month-day-year, chosen during the import) |
| Phone number | +44 20 7946 0958, extension as ext123 |
| Currency | 123.45, without a currency symbol |
| Percentage | 25% or .25 |
| Single checkbox | True / False or Yes / No |
| Multiple checkboxes | Option A;Option B (semicolons, no spaces) |
| Dropdown or radio | Exactly the option's label or internal value |
Checklist before you import
Collecting contacts from someone else?
Send them a form instead of a spreadsheet. The HubSpot Contacts template checks emails, phones and dropdown values as they're entered, flags repeated emails, and downloads a CSV with HubSpot's property names.
Try the HubSpot templateRelevant Templates
Import Builder is an independent product and is not affiliated with, endorsed by, or sponsored by HubSpot, Inc. HubSpot is a trademark of HubSpot, Inc. Import rules as described in HubSpot's knowledge base, October 2026.