A contact file is a CRM mutation plan. Protect structure, identity, property formats, blank-update behavior, and portal review before expanding beyond a controlled test.
HubSpot's official contact quick-import guide is for contact data only. Use it when one file represents contacts and you do not need company, deal, ticket, activity, association, or multi-object behavior. Those workflows have more identity and relationship rules than this page covers.
The quick path accepts .csv, .xlsx, and .xls. The file needs a header row, one contact per row, and a separate column for every property. Keep decorative titles, notes, totals, merged areas, and repeated headers out of the import range.
The private HubSpot contact CSV validator follows that contacts-only boundary. It checks local structure and selected value formats without a portal connection. It does not turn a simple file into a multi-object import or invent associations.
HubSpot's import-file setup documentation requires one sheet and fewer than 1,000 columns. If an Excel workbook contains several sheets, copying the intended range into a one-sheet workbook or CSV removes ambiguity. Selecting one sheet locally does not change the original workbook shape.
Free tools accept files up to 20 MB and count up to 500,000 imported rows per rolling 24 hours. Smart CRM and paid editions accept files up to 512 MB, document a 1,048,576-row per-file ceiling, and have higher daily row allowances. Account-wide import activity is not visible to a browser preflight, so daily limits remain a review.
Use UTF-8 when names or property labels include non-ASCII text. Give every column a nonblank, unique header. The validator preserves duplicate positions and blocks them instead of silently collapsing two properties into one.
A new contact needs at least one of First name, Last name, or Email. An update needs a unique identifier: Email, Record ID, or a custom property configured with unique values. State whether the job creates contacts, creates or updates, or updates only before judging missing identifiers.
Email values must remain unique even when a different custom unique property is used. If Record ID is mapped, HubSpot gives it precedence over other identifiers. Record IDs must come from the destination portal; a local file can check digits and duplicates but cannot prove that an ID exists or names the expected record.
Do not use a display name, owner name, company, phone, or an ordinary custom property as a match key unless that property is configured as unique in HubSpot. Importing with the wrong identity rule can create duplicates or update the wrong expectations even when every row parses.
Headers correspond to HubSpot properties and may appear in any order. During mapping, confirm each source column's destination. A missing property can be created or the column can be skipped, but that choice changes portal schema and should be deliberate rather than inferred from sample values.
The validator safely repairs only case or outer whitespace around a known default contact property label. An unknown header is preserved and marked for portal review. That prevents a business field such as Region, Segment, or Consent source from being guessed into the wrong default property.
For each column, select Text, Email, Record ID, Date/date-time, Number, Percentage, Single checkbox, Multiple checkbox, Phone, Owner, Enumeration, Additional emails, or Ignore. Default suggestions use only exact property labels; contact values are never sampled to guess a type.
Single checkbox fields accept True or Yes and False or No. Multiple checkbox options use semicolons with no spaces; a leading semicolon can append values. Enumeration and checkbox labels or internal values still need to exist on the destination property, which only the portal can confirm.
Numbers should omit currency symbols and grouping separators. Percentages may use a percent sign or a decimal according to the property's expectation. Phone values are safest in +[country code][number] ext[number] form when automatic formatting matters. Additional email addresses use semicolons.
HubSpot accepts several date forms, and the import's chosen date format controls ambiguous numeric values. Date-time properties can include time and CSV can use UNIX milliseconds. Confirm account timezone behavior; a local syntax check cannot prove the instant that HubSpot will store.
Blank cells are ignored during HubSpot imports and do not clear an existing property. Audit every update column with that behavior in mind. A file full of blanks may leave old values in place rather than replacing them with empty values.
Contact owners can be mapped by name, email, or internal value. Email or internal value is safer when users share a name. The preflight can label an Owner column, but only the destination portal can verify that the user exists and can own the record.
Marketing-contact settings, overwrite choices, workflows, lists, permissions, and automation are outside the local file contract. Record those decisions next to the import plan and have a responsible operator review the HubSpot summary screen before starting.
Run the complete file through the validator, resolve blockers, and read every warning and review. The normalized file changes only approved header repairs, CSV quoting, UTF-8 serialization, and LF endings. It preserves source order, blank cells, and every contact cell string.
Download the first-100 test CSV and inspect it in a text editor. Reduce the test further for sensitive, high-value, or automation-heavy contacts. Keep a portal export or other rollback evidence before updating existing records, because an import is a CRM mutation rather than a reversible preview.
In HubSpot, upload the test, select the contacts-only flow, map each column, set the date interpretation, and confirm the unique identifier. Review the import summary and any property-creation choices before starting. Do not scale until the destination records match the plan.
Open representative test contacts and verify identifiers, names, emails, phone values, owner, lifecycle stage, custom properties, dates, checkbox values, and automation outcomes. Compare expected and imported counts and search specifically for duplicates.
HubSpot's import-error documentation covers duplicate row content, duplicate Record IDs or unique values, invalid email or Record ID, missing properties, parse failures, owner errors, and values that violate property rules. Download the error file while it is available and keep it with the source and report.
The import-tool overview explains the broader import model. Fix the smallest understood cause, rebuild a controlled test, and repeat. A locally clean file is permission to test carefully, not proof that portal configuration and automation will behave as intended.
Yes. This local preflight checks contacts-only quick-import structure, headers, identifiers, duplicate rows and emails, selected property formats, tier limits, and workbook shape. It cannot query a HubSpot portal or guarantee acceptance.
No. Parsing, type choices, findings, masked evidence, normalization, and downloads remain in the browser tab. No contact value is sent to HubSpot or csvtodashboard.
HubSpot documents CSV, XLSX, and XLS contact files with one sheet, a header row, one contact per row, and a separate column for each property.
Email, Record ID, or a custom property configured with unique values can identify records. Record ID takes precedence when it is included, and Email still must remain unique.
No. HubSpot ignores blank cells during import, so they do not clear existing property values. Clearing values needs a separate deliberate workflow.
Separate values with semicolons and no spaces. A leading semicolon can append values instead of replacing them, but the destination property's available options still need portal review.
It checks the documented 20 MB Free tools or 512 MB paid file limit, fewer than 1,000 columns, the paid per-file row ceiling, and the Free rolling-day row limit as an account-dependent review.
No. A local file cannot prove custom property existence, owner users, enumeration options, timezone behavior, account settings, existing records, or downstream automation. Import and inspect a controlled test first.