To import contacts into HubSpot from a spreadsheet, prepare a clean CSV or Excel file, choose how existing contacts should be handled, and check the column mappings before completing the import. The key decision is which value identifies each person: usually their email address, or a HubSpot Record ID when updating known contacts.
For a small business moving out of spreadsheets, the aim is a usable customer database. We recommend starting with a small, representative batch so you can check the result before importing the rest.
Table of Contents
Choose Quick import or Advanced imports
HubSpot offers a quick contact import for straightforward contact creation or updates. It needs Import permission and does not configure associations or advanced settings. Choose it for a simple contact list when you do not need those controls.
Use Advanced imports when you need to choose between adding records, updating records, or both, or protect existing values from being overwritten. The advanced route requires Import permission and Edit permission for contacts. For a first migration into an account that already contains useful customer information, we recommend this route because those choices matter.
Prepare one clean spreadsheet
HubSpot accepts .csv, .xlsx and .xls files. Use one sheet, a header row and one contact per row. Each column should describe one property. For example, keep first name, last name and email in separate columns. Use UTF-8 encoding when your CSV contains international characters. See HubSpot’s file-format requirements.
Work from a copy. Keep the original export, your cleaned version and a brief note of what changed. Remove spreadsheet totals, explanatory notes and columns you do not intend to use. Check the whole file for repeated people and contradictory details before uploading it.
For an initial address book, a useful starting structure is:
- Email: the address you have confirmed belongs to that person.
- First name and Last name: separate fields for practical filtering and personalisation.
- Record ID: include this only for an update file containing IDs exported from this HubSpot account.
Leave optional information out of the first batch if nobody has decided how it will be used. A smaller, well-understood import is easier to check than a copy of every historical spreadsheet column.
Choose an identifier before importing
HubSpot’s identifier guidance distinguishes a person’s contact details from the value used to match their record. Email is the usual contact identifier. Record ID is HubSpot’s own identifier; export existing contacts to obtain it. When mapped, Record ID takes precedence over other identifiers.
If you are changing email addresses on existing records, use their verified Record IDs to target the intended people. Do not put IDs from an old CRM into HubSpot’s Record ID field. Keep an external reference separate if your team needs it.
For mixed data, consider two files: one for confirmed existing contacts with their Record IDs, and one for new contacts. This makes the intended result easier to review.
During an email-based import, a matching address updates the existing contact rather than creating another. This does not mean HubSpot recognises every spelling variation or knows that two different addresses belong to the same person. Review those cases yourself. HubSpot’s deduplication documentation also explains why omitting identifiers can create new records.
Upload the file and check every mapping
For a simple import, the current Quick import procedure is:
- Open Data Management → Data Integration; your navigation may place it under More.
- Start an import and choose the quick contact option.
- Upload your file, or paste the copied spreadsheet data.
- Review the mapped contact properties and correct unmatched columns.
- Name the import, read the consent confirmation and complete the import when it accurately applies.
For Advanced imports, select Contacts and choose the intended behaviour. The single-object instructions provide three options: create and update, create new only, or update existing only. The last two ignore records outside the selected purpose.
Check the identifier first, then the destination for every remaining column. A column called “Customer reference” should not be mapped to Record ID just because it contains numbers. Use the existing property whose purpose matches the information, create an appropriate custom property if needed, or skip the column.
In the advanced mapping screen, use the option to prevent overwriting existing values where appropriate. Confirm date and number formats if your file includes those fields. Do not accept a plausible-looking preview without checking what each column means.
Run a small batch and inspect actual records
Our suggested first batch is five to ten legitimate contacts covering the situations in your file: a new person, an existing person to update, a record with optional fields blank and any unusual characters. This is an editorial recommendation, not a HubSpot minimum or a simulated import mode: completing the import makes real changes.
Before starting, write down the expected outcome for each row. For an illustrative ten-row batch containing seven new people and three existing contacts, you would expect seven creations and three updates if every row is valid and uniquely identified.
Use the import name to make that batch easy to find. HubSpot’s import history shows creation, update and error counts and lets you view records from the import. Open several records and compare them with your notes:
- Did the right person receive the update?
- Are names and email addresses in the intended fields?
- Did information you wanted to preserve stay intact?
- Can another team member understand and use the imported information?
Keep the successful test rows out of the remaining upload, so you have a clear record of which batch handled each contact.
Resolve errors before importing the remainder
An import can succeed for a contact while rejecting one property value. Check the error impact, not just the total number of records. HubSpot provides an error download identifying affected rows and reasons in its import troubleshooting guide.
| Problem | What to check |
|---|---|
| Invalid Record ID | Compare it with a fresh HubSpot export. An ID from another system will not identify a HubSpot record. |
| A dropdown value is missing | Check whether the spreadsheet value matches an allowed option for that property. |
| A date is missing or reversed | Check the date format selected for the import against the file’s day and month order. |
| A column did not import | Check its header and property mapping. |
Correct the affected data and review the matching identifiers before retrying. Keep a short correction log so a later import does not bring the same problem back.
Check limits and marketing status
HubSpot currently lists free-tool import limits of 20MB per file, 50 imports and 500,000 rows per rolling 24 hours. Paid-account limits differ. Check the current limits before a large migration. Also, a blank spreadsheet cell does not clear an existing HubSpot value.
For accounts using marketing contacts, setting a person as marketing counts towards the billable contact tier. HubSpot says newly imported contacts default to non-marketing when no marketing status is specified. Review the marketing contact settings deliberately; importing an address book and choosing a marketing audience are separate decisions.
If you are still deciding which HubSpot features you need, see our HubSpot free versus paid guide for startups. Once the contact data is correct, our HubSpot Gmail integration guide covers connecting everyday sales conversations to the CRM.
Checked 11 September 2026 against official HubSpot documentation. Examples are illustrative.
