DocTransform
All import guides

HubSpot won't import your contacts file?

Fix the errors HubSpot shows when importing a contacts CSV, then import clean every week.

Errors HubSpot shows

A required property is missing

Missing required property
HubSpot help centre

A property marked unique is duplicated

Duplicate unique property value
HubSpot help centre

A date does not match the format you picked

Could not parse date
HubSpot help centreHow to fix this error

What HubSpot’s importer checks

  • Every property your portal marks required, Email included, must have a value.

    we point out a blank in a column you mark required: open the column ⋯ menu → Edit column… → More options → Required Field, and the Invalid filter over the grid shows each blank

    HubSpot skips the row

    HubSpot help centre

    Last checked October 25, 2026

  • A property marked unique, like Email, must not repeat within the file.

    DocTransform fixes this: type

    Lowercase Email and remove rows with a duplicate Email

    Or by hand

    click the Email column header → lowercase, then Remove duplicates; the repeat contact’s row is removed

    HubSpot imports it wrong, with no error

    HubSpot help centre

    Last checked October 25, 2026

  • A Phone Number must be written as +[country code][number].

    DocTransform fixes this: type

    Write Phone number as E.164

    Or by hand

    open Health → Phone numbers written different ways → Rewrite 4 values (the button shows how many numbers it writes); each readable number is written as +[country code][number], and one it cannot read stays as written

    HubSpot imports it wrong, with no error

    HubSpot help centre

    Last checked October 25, 2026

  • The file must be a single-sheet CSV, XLSX or XLS with one header row, under 1,000 columns and UTF-8 encoded for non-English characters.

    HubSpot refuses the file

    HubSpot help centre

    Last checked October 25, 2026

  • The file needs a column named Email.

    DocTransform fixes this: open the column’s ⋯ menu → Edit column… → click the name at the top of the drawer, rename it to Email and press Enter

    HubSpot refuses the file

    HubSpot help centre

    Last checked October 25, 2026

  • Each Email must be a complete address, like name@example.com.

    we point out an invalid address once you mark the column required (column ⋯ menu → Edit column… → More options → Required Field; the Invalid filter over the grid shows each); clicking the Email column header → Trim spaces, then lowercase, trims spaces and fixes case, but a badly-formed address is yours to fix

    HubSpot skips the row

    HubSpot help centre

    Last checked October 25, 2026

  • A Date of birth must be written the way HubSpot reads it, like YYYY-MM-DD.

    DocTransform fixes this: open the Date of birth column’s ⋯ menu → Format dates… → output YYYY-MM-DD (2024-12-31) → Save Rule

    HubSpot imports it wrong, with no error

    HubSpot help centre

    Last checked October 25, 2026

  • A Date of birth like 03/04/2024 can be read with the day and the month swapped.

    DocTransform fixes this: open the Date of birth column’s ⋯ menu → Format dates… → pick the order the dates are written in, output YYYY-MM-DD → Save Rule

    HubSpot imports it wrong, with no error

    HubSpot help centre

    Last checked October 25, 2026

  • A Lead Status must be one of the options your portal lists, or HubSpot leaves it blank.

    DocTransform fixes this: open the Lead Status column’s ⋯ menu → Find & replace…, find the value, Replace with the option your portal lists, Match entire cell → Replace all

    HubSpot imports it wrong, with no error

    HubSpot help centre

    Last checked October 25, 2026

  • Interests with more than one value are separated by a semicolon, with no space beside it.

    DocTransform fixes this: open the Interests column’s ⋯ menu → Find & replace…, find a comma and the space after it, Replace with ;, Match part of cell → Replace all

    HubSpot imports it wrong, with no error

    HubSpot help centre

    Last checked October 25, 2026

  • A cell over 1 MB makes HubSpot skip its row; shorten very long text in the source file.

    HubSpot skips the row

    HubSpot help centre

    Last checked October 25, 2026

Before and after

8,204 contacts

newsletter_signups.xlsx
EmailFirst namePhone numberEmail subscriptions
Ines@SolyMar.example1Ines Ruiz+34 600-123-4562Newsletter, Events3
ines@solymar.example4Ines Ruiz+34600123456Webinars
marc.bloch@nordic.exampleMarc Bloch+46701234567Newsletter
julia.novak@praha.exampleJulia Novak+420.601.234.567Events
tomas.silva@lisboa.exampleTomas Silva+351 912 345 6785Newsletter, Webinars
anna.keller@wien.exampleAnna Keller+436601234567Webinars
leo.martin@paris.exampleLeo Martin+33 6 12 34 56 78Newsletter

    Fix it in DocTransform

    By hand: 14 stepsDocTransform: 1 sentence

    1. 1. Upload newsletter_signups.xlsx into DocTransform.
    2. 2. Type

      Lowercase Email, remove rows with a duplicate Email, replace the comma followed by a space in Email subscriptions with a semicolon and write Phone number as E.164

      and press Send. Check the steps it adds; Undo takes them all back.
      Or by hand

      Apply the fixes: click the Email column header → lowercase, then Remove duplicates to drop the repeat contact; open the Email subscriptions column’s ⋯ menu → Find & replace…, find a comma and the space after it, replace with ;, Match part of cell → Replace all to join the topics HubSpot expects. Then open Health → Phone numbers written different ways → Rewrite 4 values to write each phone number as +[country code][number].

    3. 3. Download the cleaned file as CSV, ready for HubSpot’s importer.
    “Lowercase Email, remove rows with a duplicate Email, replace the comma followed by a space in Email subscriptions with a semicolon and write Phone number as E.164” typed into DocTransform; four steps applied, one duplicate row removed, subscription topics joined with semicolons, phone numbers written as E.164 with their country code; Undo shown
    1. Type the change in one sentence, in your own words.
    2. Wait about 5 seconds while the steps are written. Stop cancels.
    3. Check each step and how many cells or rows it changes.
    4. The file is clean. Not what you meant? One Undo takes it all back.

    Save this fix once, then rerun it on next week’s export with one click.

    Fix it by hand in Excel or Sheets

    1. Right-click the column B header and choose Insert to add an empty helper column next to Email.
    2. In B2, type =LOWER(A2) and press Enter.
    3. Double-click the fill handle at B2’s bottom-right corner to fill the formula down to the last row.
    4. With the filled cells in column B still selected, press Ctrl+C to copy them.
    5. Select A2, choose Home → Paste → Paste Special → Values and click OK, so Ines@SolyMar.example becomes ines@solymar.example.
    6. Right-click the column B header and choose Delete to remove the helper column.
    7. Click any cell in the table, choose Data → Remove Duplicates, click Unselect All, tick Email and click OK to drop the repeat Ines Ruiz row.
    8. Click the column D header (Email subscriptions), then choose Home → Find & Select → Replace.
    9. Type a comma and a space in Find what, type ; in Replace with, and click Replace All, so Newsletter, Events becomes Newsletter;Events.
    10. Select a column you’ll mark required in HubSpot, then choose Home → Find & Select → Go To Special → Blanks and click OK to highlight its empty cells.
    11. Type a value into each highlighted blank cell by hand, and repeat both steps for every required column.
    12. Right-click the column C header (Phone number), choose Format Cells → Text and click OK, so Excel keeps the leading +.
    13. Retype each phone number by hand without spaces or punctuation, e.g. +34 600-123-456 as +34600123456.
    14. Choose File → Save As, pick CSV UTF-8 (Comma delimited) (*.csv) and click Save; if Excel warns about multiple sheets, click OK to save this one only.

    Questions

    Does DocTransform split my file if it’s over HubSpot’s limits?
    Yes, by rows. In Export Studio choose Split into files → By number of rows… and set the most rows each file may hold: you download one .zip and upload the files one at a time. It splits by rows, not by size, so it cannot promise a file stays under a size limit: check each file before you upload it.
    Will DocTransform know which properties HubSpot requires?
    Some of them. It knows the checks HubSpot publishes for a contacts file, listed above with the date each was last checked. Your own portal’s required properties are yours to name: mark them in the Health panel, and it flags the blanks for you.
    Can I reuse this fix next time I export contacts?
    Yes — save it once in DocTransform and rerun it on next week’s export.
    Try this sentence free

    Free plan, no card required.

    Salesforce, HubSpot, Shopify, QuickBooks, Mailchimp, Pipedrive, WooCommerce, Klaviyo, Google Contacts, ActiveCampaign, Brevo, Zendesk, Square, Zoho CRM, and Xero are trademarks of their owners. DocTransform is not affiliated with them.