This guide walks you through importing your HubSpot data (contacts, deals, custom fields, and pipelines) and reviewing the import results so you can spot and fix any errors.

Before you start

  • You'll need a HubSpot service key with read-only access. If you don't have one yet, follow How to create a HubSpot service key first.
  • Use a clean account. We recommend importing into an account that doesn't already have manually created data — mixing imported and manual records makes errors and duplicates harder to untangle. Spin up a fresh sub-account for the import if you can.
  • Turn on "Allow duplicates" for both Contacts and Opportunities before you start. Leaving duplicate-blocking on causes a lot of avoidable errors during a HubSpot import — you can re-enable de-duplication after the import is done.
  • The import runs in the background. You can close the window and come back later — progress is preserved.

Step 1 — Open Import data and choose HubSpot

From Contacts (or Opportunities), open the Import menu in the top-right and select Import data. You'll see two import methods.

Click Connect HubSpot in the right card to start a HubSpot import.

The Import data page showing two import methods: Import records from CSV and Import from HubSpot.

Step 2 — Paste your service key

Paste your HubSpot service key into the Hubspot Service Key field, then click Verify & Connect. Your key is encrypted and never stored in plain text.

Don't have a service key yet? See How to create a HubSpot service key first.

The Connect HubSpot panel with a service key pasted into the Hubspot Service Key field and the Verify & Connect button enabled.

Step 3 — Review the quick tips

Once your key is verified, the import wizard opens at Get started. This step shows a quick walkthrough video and a few tips:

  • Clean up duplicates in HubSpot before importing.
  • Back up your current data before importing.
  • Review field mappings before you start the import.

When you're ready, click Continue.

The Get started step of the import wizard, with a quick-tips video, link to the import guide, and tips for a successful import.

Step 4 — Select what to import

Choose which HubSpot objects to bring over:

  • Contacts — people you track (leads, customers, prospects).
  • Deals — pipeline value and status. Deals are imported as Opportunities. Importing Deals requires Contacts — Contacts will be auto-selected if you pick Deals.

Tick the boxes for what you want, then click Continue.

The Select objects step showing two cards: Contacts and Deals, with checkboxes to choose which to import.

Step 5 — Review what's included

The wizard automatically includes the related data needed to keep your records complete and connected:

  • Contacts: all properties (standard + custom fields).
  • Deals: all properties + pipelines. Pipeline stages are imported along with pipelines — you don't need to recreate them.

Two things to watch for with custom fields:

  • Custom fields are mapped by key. If a custom field with the same key already exists in your account, the import will throw an error for that field. Rename or remove the existing one before importing if you want a clean mapping.
  • Mismatched name vs. label. If a custom field's internal name and display label are different in HubSpot, you may see issues during import. Reviewing your HubSpot custom fields and aligning name/label before importing avoids surprises.

Click Continue to move on.

The Review included data step showing Contacts (Properties) and Deals (Properties and Pipelines) included by default.

Step 6 — Confirm record counts

Before the import starts, the wizard shows what will be brought over and how many records are involved. For each row you'll see:

  • HubSpot data — what's in HubSpot (e.g., Contacts – records, Deals – pipelines).
  • Imported as — what it becomes in your account (e.g., Contacts – custom fields, Opportunities – pipelines).
  • Records found — how many records will be imported.

Heads-up: the Records found count for custom fields can differ from what you see in HubSpot's UI. The wizard counts only fields it can map and import, so a small gap between the two numbers is expected.

Click Confirm and start import to kick it off. Confirm once more in the dialog that follows.

The Preview and import step showing a Confirm import details table with HubSpot data, Imported as, and Records found counts.

Step 7 — Your import is running

You'll see a confirmation at the top of the page: Your HubSpot import has started and is running in the background. The Import history table below shows the in-progress run with a live Processing % status.

You can close the window or navigate away — the import keeps running. Come back to this page anytime to check progress.

A success toast at the top reading Your HubSpot import has started, with the Import history table below showing the in-progress run.

Step 8 — Open Import details (Object view)

When you're ready to review results, click the eye icon in the Actions column of an import row. The Import details modal opens.

The four cards at the top give you the headline numbers:

  • Total records — everything the import touched.
  • Success — records that imported cleanly (with the success rate).
  • Errors — records that didn't import.
  • Imported with warnings — records that imported but have something worth reviewing.

Object view (the default tab) summarises each object: how many succeeded, how many errored, and overall status.

The Import details modal in Object view, showing total records, success, errors, and imported-with-warnings counts plus a per-object summary table.

Step 9 — Drill into individual records

Switch to the Record view tab to see every record one row at a time.

Use the filters at the top:

  • Objects — narrow to Contacts, Contacts – Custom field, Opportunities, etc.
  • Status — filter by Success, Error, or Imported with warnings.

The screenshot above shows the Success filter — every row that imported cleanly.

The Import details modal in Record view, filtered to Status = Success, showing successfully imported records.

Step 10 — Review and fix errors

Switch the Status filter to Error to see every record that failed. Each row tells you which object failed and why, with the HubSpot record ID in the message so you can find it back in HubSpot.

Click Download in the bottom-left to export the full error list as a CSV — useful for fixing data in HubSpot, then re-running the import.

Common error causes are covered in the FAQ below.

The Import details modal filtered to Status = Error, showing rows of failed records with error messages referencing HubSpot record IDs.

Troubleshooting & FAQ

The Verify & Connect button gives me an error.

Double-check that your service key starts with pat- and that all four read-only scopes (crm.objects.contacts.read, crm.objects.deals.read, crm.schemas.contacts.read, crm.schemas.deals.read) are attached to the key. If it still fails, generate a fresh key in HubSpot and try again.

The "Records found" count is lower than what HubSpot shows.

The wizard's count includes only fields the import can actually map and bring over. Some HubSpot fields are excluded (for example, fields with unsupported types), so you may see a small gap between HubSpot's UI and the count in the import preview. The records that don't make it into the count are the ones the import would skip anyway.

I see errors saying "Couldn't import contact with HubSpot record ID…"

That message tells you exactly which HubSpot contact failed. Common reasons:

  • The contact has a file attached to a field. File imports aren't supported yet — any contact (or deal) with a file attachment will throw an error. Workaround: download the file from HubSpot, remove the attachment from that field, then re-run the import. The file itself can be re-attached manually after import.
  • Custom field key collision. Custom fields are mapped by their internal key. If a field with the same key already exists in the destination, the import errors on that field. Rename or delete the existing field before importing.
  • Custom field name and label don't match. When a HubSpot field's name and label differ, the importer can get confused about which one to use. Aligning them in HubSpot before importing usually clears it up.

Can I re-import or pick up where I left off?

Yes — start a new import from the Import data page. Each run is logged separately in Import history, so you can compare runs and check the error CSV from a previous attempt before re-running.

Does the import overwrite existing records?

By default, no. Imported records are added alongside whatever's already in your account. That's why we recommend importing into a clean account — and why "Allow duplicates" should be on during the import (see Before you start).

Where can I see the full list of errors?

Open Import details from any import row, switch to Record view, set Status to Error, then click Download to export the full list as a CSV.