Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท CRM Basics

Importing Data into HubSpot

Prepare and import contacts, companies and deals into HubSpot from CSV or Excel: file layout, column mapping, unique identifiers, associations and avoiding duplicates.

Most HubSpot projects begin with an import: contacts from a spreadsheet, customers from an old CRM, event attendees from a conference. A careless import creates duplicates and bad data that take weeks to repair, while a careful one takes an hour. The difference is preparation.

Where imports live

From the CRM area (for example Contacts), choose Import (top right). The wizard asks you to choose Start an import, then File from computer, then One file (or Multiple files for related objects), and finally the objects you are importing. HubSpot accepts CSV, XLS and XLSX files. Exact wording changes, but the flow is stable: upload, map columns, review, finish.

Prepare the file

Before you upload, clean the sheet:

  1. One header row. The first row holds column names; every other row is one record.
  2. One object per row, one record per row. Do not merge cells or use blank spacer rows.
  3. Unique identifier column. Contacts need Email; companies need Company domain name; for other objects use Record ID or a property marked unique. Without one, HubSpot may create duplicates.
  4. Consistent values. For dropdown properties, values must match the option internal value or label exactly. "Pro" does not match "pro" in every case.
  5. Dates in a consistent format (HubSpot asks which format your file uses).
  6. Split full names into First name and Last name columns if you can.
  7. Remove junk: test rows, role addresses you will never email, obviously invalid emails.
  8. UTF-8 encoding for CSV files, so accented characters survive.

Keep an untouched copy of the original file. When something looks wrong after import, you need to know whether the error was in the source or in your mapping.

Mapping columns

HubSpot suggests a mapping from your header to a property. Review every column:

  • Map to an existing property when one fits (First name, Phone number).
  • Create a new property from the wizard if none exists. Pick the right field type now.
  • Do not import a column you do not need.

For dropdowns, a mismatch produces an error for that row, and HubSpot offers to map unrecognized values or skip them.

Create versus update

An import can do three things depending on the settings and the file:

  • Create new records for rows whose identifier is not found.
  • Update existing records when the identifier matches. Be careful: HubSpot overwrites with the file value. Blank cells in the file usually do not clear existing values unless you choose a setting to overwrite with blanks, so you can import partial data safely.
  • Create and update together, the default for contacts: email decides.

Importing associated data

You can import multiple objects in one file and link them, for example a contacts sheet with a company name and domain per row. HubSpot creates the companies and associates the contacts with them. Alternatively, import several files and supply an identifier to connect them (a contact's email plus a company domain, or a deal's record ID with the contact's email). Always import companies first, then contacts and deals, so there is something to associate with.

Imports can set whether imported contacts are marketing contacts, and your legal basis to email them. Be honest here: marking contacts who never agreed to marketing as "marketing contacts" can breach anti-spam law (GDPR, CAN-SPAM, CASL) and raises your bill. Record where the data came from in a property such as Original source or a custom "Import source".

After the import

  1. Open the import history (Contacts > Import > the list of imports) to see counts of created, updated and errored rows, and download the error file.
  2. Spot-check ten records: properties, owner, associations.
  3. Create a static list of the imported records so you can find them (HubSpot also tags records with an import name you can filter on).
  4. Run a duplicate review (see data quality and deduplication).

An import can be undone in some cases (deleting the records it created), but updates are not reversed, which is why testing on a small file first is wise.

A pre-flight checker (stand-in)

This stand-in is not HubSpot's importer. It validates a CSV the way you should before uploading, and shows how email decides create versus update.

JS Stand-in: pre-flight check of a contacts CSV

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: create versus update by email

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that Ana keeps her phone number even though the import row had a blank phone.

Common import mistakes

  • Importing without a unique identifier and creating duplicates.
  • Saving the CSV in a non-UTF-8 encoding so "Josรฉ" becomes garbage.
  • Typing dropdown values differently from the options.
  • Importing everyone as marketing contacts.
  • Importing deals before companies exist.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which column does HubSpot use to decide whether a contact row creates or updates a record?

    Email is the unique identifier for contacts, so a match updates and a miss creates.
  2. 2. What usually happens to an existing value when the file cell is blank?

    By default blank cells do not clear existing data, so partial updates are safe.
  3. 3. In what order should related objects be imported?

    Having companies in place lets contacts and deals associate with them.
  4. 4. What is a good habit after an import?

    Verification catches mapping mistakes early, while the original file is still at hand.

Summary

  • Imports accept CSV, XLS and XLSX; prepare one header row and a unique identifier.
  • Map columns carefully and match dropdown values exactly.
  • Email decides contact create versus update; blank cells normally keep existing data.
  • Import companies first, verify results and respect consent and marketing-contact status.

Next: Associations and lifecycle stages