How to Prepare CSV for HubSpot Contacts Import

By Online CSV Editor · Last updated: 2026-04-09

The safest way to prepare a HubSpot contacts CSV import is to start from the contact properties you actually need, then verify headers, unique identifiers, picklist values, dates, consent-related fields, and duplicate risk before a full upload. Most HubSpot import problems come from mapping and data-quality issues rather than from CSV itself.

If this file is part of a broader handoff workflow, start with the CSV import and export guide. If the contact list still needs cleanup first, pair this page with how to rename CSV headers safely and how to validate email columns in CSV.

Quick answer

  1. Start from HubSpot contact properties or a known-good export, not from guesswork.
  2. Match property headers deliberately and remove columns you cannot map with confidence.
  3. Confirm the unique identifier you will use, usually email for contact imports.
  4. Normalize lifecycle stage, phone, country, date, and consent-related values before upload.
  5. Run a small sample import first to verify mapping, duplicate handling, and field behavior.

What HubSpot contacts CSV format really means

People search for hubspot contacts csv format as if there is one universal spreadsheet shape. In practice, HubSpot contact imports depend on the properties in your portal, the identifiers you use for matching, and whether you are creating new contacts, updating existing ones, or both.

  • Headers need to match intent. Loose column names make property mapping slower and riskier.
  • Identifiers need to be stable. Email is common, but whatever key you choose should be clean and consistent.
  • Property values need normalization. Picklists, dates, phone numbers, and country fields often fail because formats drift.
  • Consent and lifecycle fields need care. CRM imports can create compliance or routing problems when these values are messy or outdated.

Step-by-step: how to prepare a HubSpot contacts CSV import file

  1. Start with the destination schema. Use the HubSpot properties you intend to populate, a recent successful export, or the current import guidance as the source of truth instead of inventing a column layout.
  2. Clean the header row first. Rename vague source columns, remove duplicates, and drop values you cannot map confidently to contact properties.
  3. Validate the identifier strategy. For many contact imports, email is the cleanest identifier. Make sure blanks, typos, aliases, and duplicates are handled before upload.
  4. Normalize high-risk contact properties. Review lifecycle stage, lead status, owner mapping, first and last name casing, phone number formatting, country names, and date fields so HubSpot does not receive mixed-value chaos.
  5. Check consent-sensitive columns. If the file includes subscription, opt-in, or legal-basis fields, confirm the values reflect your actual workflow instead of blindly importing legacy status values.
  6. Review duplicates and update intent. Decide whether repeated contacts should update existing records, be merged beforehand, or be excluded from the file.
  7. Test a small batch. Import a small sample so you can catch property mapping mistakes, duplicate logic issues, and date or picklist problems before the full contact list goes in.

Common HubSpot contacts CSV mistakes

  • Using source-system headers that do not clearly map to HubSpot contact properties.
  • Importing contacts with malformed, blank, or duplicated email identifiers.
  • Mixing lifecycle stage or lead status values that do not match the destination options.
  • Letting spreadsheet tools reformat dates, phone numbers, or ZIP codes before export.
  • Uploading a full contact list before testing duplicate behavior on a small sample.

Example: cleaning a webinar signup export for HubSpot

Imagine you export signups with columns such as Email Address, First Name, Last Name, Phone, Company, Country, and Webinar Date. The file opens correctly, but it is not yet HubSpot-ready.

  1. Rename source headers to the HubSpot contact properties you actually plan to map.
  2. Validate email rows and remove blanks, typos, or obvious duplicates.
  3. Normalize phone numbers, countries, and dates to one consistent rule.
  4. Decide how new signups should map to lifecycle stage or lead-status values.
  5. Test a small import and review whether records create or update the way you expect.

How this page differs from ecommerce import guides

This page focuses on HubSpot contact imports, not product catalogs or generic spreadsheet QA. That keeps the intent separate from ecommerce pages such as the Shopify CSV format guide and broader workflow pages such as the CSV import checklist. If your main problem is email quality before CRM import, go deeper with the email validation guide.

Quick checklist before upload

  • Headers map cleanly to the HubSpot contact properties you intend to use.
  • Email or the chosen identifier is clean, unique enough for the workflow, and intentionally mapped.
  • Lifecycle stage, lead status, dates, phone numbers, and country values are normalized.
  • Consent-sensitive fields were reviewed intentionally instead of copied blindly.
  • A small sample import succeeds before the full contact upload.

FAQ

What format does HubSpot want for contacts CSV import?

HubSpot wants a clean contacts CSV with mappable property headers, one row per contact, a stable identifier such as email when applicable, and values formatted for the destination properties.

Why does a HubSpot contacts import fail even when the CSV looks fine?

Because HubSpot validates mapping, duplicate behavior, picklist values, dates, and identifiers. A file can look neat in a table and still contain values that import badly.

Should I include every contact property in the CSV?

No. Include the properties you actually trust and need. Extra low-quality columns increase mapping risk and create cleanup work inside the CRM.

Should I test a small import first?

Yes. A small test import is the safest way to confirm create-vs-update behavior, property mapping, and duplicate handling before you upload the full file.

Canonical: https://csveditoronline.com/docs/hubspot-contacts-csv-format