Set up your import files
Last updated: December 28, 2021
|All products and plans|
Whether HubSpot is your first CRM or you’re moving from another system, importing helps you create records and update your database. Import files are spreadsheets of data used to organize your business’ relationships and processes. Before you start importing, review the relevant HubSpot terms and requirements for your import files.
Please note: engagements (emails, calls, tasks, or meetings) associated with your records cannot be imported via a file into HubSpot. Learn more about adding engagements using the API.
CRM Object: a type of a relationship or process that your business has, such as contacts, companies, deals, and tickets. When importing, an object is the type of dataset you are importing into HubSpot.
Record: an individual instance of an object (e.g., “Tom Smith” is a contact record). In a single object import file, each row of your file represents one object record. If you are importing multiple objects in one file, each row will represent records that are associated with each other.
Property: a field created to store information about your records. In an import, properties will match up with your file’s column headers.
In this example, the object being imported is contacts. Each row represents a contact record, and each column of information represents a contact property (First Name, Last Name, Email Address).
- Unique identifier: a property value that HubSpot uses to recognize each record as one of a kind. In an import, you need a unique identifier to associate two different records (e.g., import “Tom Smith” and associate him with his company “Smith Inc.”), or to avoid creating duplicate records (e.g., two records for “Tom Smith”). The unique identifiers used when importing into HubSpot are:
- Email: the email address of a contact. This is required when importing and associating contacts with another object via an import. If you don’t have contact email addresses, use the Contact ID to update and associate existing contact records.
- Company domain name: the website domain of a company (e.g., example.com). This is required when associating companies with another object via an import. If you don’t have company domain names, use the Company ID to update and associate existing company records.
- [Object] ID: a unique property value given to each record by HubSpot. If you export existing records from HubSpot, each record will have an [Object] ID. This is a required column when importing and associating existing deals or tickets with another object type, but can also be used as the unique identifier for contacts and companies if you do not have emails or company domain names.
Map columns: a step in the import process, when you will be prompted to match the column headers in your file to HubSpot properties.
As an example, you want to import and associate contacts and companies in one file. The objects being imported and associated are contacts and companies. Each row represents a contact record and its associated company record. Each column header represents properties that will be mapped during import. The file shown below includes contact properties (First name, Last name, Email address, Phone number, Favorite food) and company properties (Name, Company domain name). There is also a unique identifier for each object that will link the two unique records in HubSpot (Email address for contacts and Company domain name for companies). During the import process, you will map columns to HubSpot properties (First Name column to the First Name HubSpot property).
Mapping columns to properties
File requirementsAll files being imported into HubSpot must:
- Be a .csv, .xlsx, or .xls file.
- Have only one sheet.
- Contain fewer than 1,048,576 rows and 1,000 columns.
- Be smaller than 512 MB.
- Include a header row in which each column header corresponds to a property in HubSpot. You can confirm if a default property already exists to match your header or create a custom property prior to importing. Learn more about HubSpot's default properties for contacts, companies, deals, and tickets.
- Be UTF-8 encoded if foreign language characters are included.
- Contain cells in Number format if you're importing date-time properties in an Excel file.
- Depending on the object(s) you are importing, your file must include the following columns:
- Contacts: First name, or Last name, or Email (unique identifier)
- Companies: Name or Company Domain Name (unique identifier).
- Deals: Deal name, Pipeline, and Deal stage.
- Tickets: Ticket name, Pipeline, and Ticket status.
- Products: Name, and Unit price.
- Notes: Activity date, and Note body.
- For properties containing a date, your date values must be formatted as one of:
- mm/dd/yyyy (e.g., 10/28/2020)
- dd/mm/yyyy (e.g., 28/10/2020) or
- yyyy-mm-dd (e.g., 2020-28-10).
Please note: if you're importing a default HubSpot date property (e.g., Close date), your values must include both a date and a timestamp. The date-time property cells must be in Number format if importing an Excel file. Learn more about how to format timestamp values and how to convert a date into UNIX format.
- To assign an owner to your contacts, companies, deals, or tickets during the import, include a [Object] owner header and add the email address of the user to each row in that column. users who are assigned a record through import will not receive a notification that they were assigned a new record.
- To update existing records and avoid duplicate records, your files must include a unique identifier property for each object. For contacts and companies, this can be Email and Company domain name. For all objects, you can export existing records and use the [Object] ID as a unique identifier. When importing [Object] ID in a file, you must include the column header exactly as it appears in the export file (e.g., Contact ID, not CONTACT ID).
Please note: you can use a secondary email as the unique identifier for existing contacts who have a secondary email address listed in HubSpot. If you use a secondary email, and do not include the Contact ID column in your file, the secondary email will not replace the primary email. However, if you include both the secondary email and Contact ID as columns in your file, the secondary email will replace the primary email.
- Depending on the property field type, there are specific formatting requirements. Learn more about property field types and importing to checkbox properties.
- When importing products (Professional and Enterprise only):
- If you want to import a Term property value, format the value in the Term column as PXM, where X is the number of months (e.g., P6M, for a term of 6 months) or PXY, where X is the number of years (e.g., P1Y, for a term of 1 year).
- If you want to import a Billing frequency property value, use monthly, annually, or quarterly if the product has a recurring price type. Leave the cell blank if the product has a one-time price.
Sample import files
The following files include the required column headers for each object type, as well as possible additional headers. You can add your own column headers to update or create any additional properties that are important to maintain your organization’s HubSpot database.
- Contacts sample spreadsheet: XLSX or CSV
- Companies sample spreadsheet: XLSX or CSV
- Deals sample spreadsheet: XLSX or CSV
- Tickets sample spreadsheet: XLSX or CSV
- Products sample spreadsheet: XLSX or CSV
Please note: products can only be imported in a single object import and cannot be associated with another object via an import. Learn how to manually associate a product to a deal or quote.
Multiple objects with associations
You can import and associate objects either together in one file or in two separate files, where each file represents one object.
Import multiple objects in one file
To import and associate multiple objects in one file, include the records you want to associate within the same row of your file. These sample files represent common use cases, but you can mix and match objects by replacing the column headers with the properties of another object.
- Contacts and companies sample spreadsheet: XLSX or CSV
- Contacts and tickets sample spreadsheet: XLSX or CSV
- Companies and deals sample spreadsheet: XLSX or CSV
- Companies and notes sample spreadsheet: XLSX or CSV
- Companies, deals, and notes sample spreadsheet: XLSX or CSV
Import multiple objects in two files
When importing and associating in two files, each file represents an object. To identify which records should be associated across the files, include a common column in both. One of your files should have a unique value for each row in this column. In the other file, use those values to indicate which record each row should be associated with.
For example, a common use case is to import and associate contacts and companies. In the following sample files, Company Name is the common column:
In the company file, there is a unique value for each row in the Company name column. In each row of the contacts file, the values in the Company name column match the company that the contact will be associated with.
You can use these files when importing contacts and companies, or mix and match other objects, as long as you include a common column. Once your files are ready, learn how to import one object or import and associate multiple objects into HubSpot.
Set up score properties to qualify contacts, companies, and deals
Users in Professional and Enterprise accounts can customize the default HubSpot score contact property to...Knowledge Base
Import one object
You can import files to create and update HubSpot records in bulk. This article explains how to import a...Knowledge Base
Troubleshoot import errors
When importing records into HubSpot, you may encounter errors. Below, learn how to download an error file,...Knowledge Base