Understand the import tool

Import to add objects—such as contacts, companies, deals, services, and activities—to HubSpot. By uploading a spreadsheet and mapping its columns to HubSpot properties, you can create new records, update existing ones, and define relationships between them. Review the import process and terminology below to ensure your data is formatted correctly before uploading your file.

If you're new to HubSpot and want to migrate your existing CRM data to HubSpot's CRM, you can request a data migration from HubSpot's Replatforming team.

Glossary

• CRM Object: your customers and business process information, such as contacts, companies, deals, and tickets. When importing, an object is the type of dataset you're importing into HubSpot.

• Record: an individual instance of an object (e.g., “Neal Caffrey” is a contact record). In a single object import file, each row of your file represents one object record. If you're importing multiple objects in one file, each row will represent records that are associated with each other.

• Activity: an engagement that can be associated with records, such as an email sent to a contact, or a note logged on a ticket record. For the import tool, supported activities include calls, emails, meetings, notes, and tasks.
• Property: a field created to store information about your records and activities. In an import, properties will match up with your file’s column headers.

In the following 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).

Supported objects and activities

The following are the types of imports you can complete, and the objects and activities supported for each.

Single object or activity import

You can import to create and/or update one object or activity at a time. In a single object import:

• You can create and/or update contacts, companies, deals, tickets, appointments, courses, listings, services, calls, products, projects, orders, carts, subscriptions, and custom object records.

• You can create, but not update, tasks.

Multiple object and activity import

You can import to create, update, and/or associate multiple objects and activities at once. You can import multiple objects and activities in one file, or two objects/an object and an activity in two separate files. When using two separate files, the files must contain a shared column.

In a multiple object import:

• You can create and/or update contacts, companies, deals, tickets, appointments, courses, listings, services, calls, orders, projects, carts, and custom object records.
• You can create and/or update line items, but they must be associated with deals.
• You can create, but not update, emails, meetings, notes, and tasks. Emails, meetings, and notes must be associated with an object.

Example: use two files to import two objects

You have two files from a different database to bring into HubSpot, one contains contacts and one contains deals. They both share a Deal name column, which matches up to the associated contact in the contact file. During the import, use Deal name as the common column and the unique key for the contact file. This allows the column to populate the Deal name property while associating the deals to contacts in HubSpot.

Other types of imports

You can also access the import process for other tools from the import page, however, these follow different steps than object or activity imports.

• Opt-out spreadsheet imports
• Custom event imports
• Dataset imports

Set up import files

Before uploading a file to the import tool, it's important to set up your files properly to make sure data is added correctly to your account. The following sections include important concepts and requirements for correctly setting up your files.

For pre-built sample files, refer to this article.

Requirements

Refer to the set up your import files article for technical limits and general requirements.

Unique identifiers

A unique identifier is a property value that HubSpot uses to recognize each record as one of a kind. In an import, you need a unique identifier to update records, avoid creating duplicate records (e.g., two records for “Tom Smith”) and to associate records with each other (e.g., import “Tom Smith” and associate him with his company “Smith Inc.”). For contacts and companies, it's recommended to use their respective unique identifiers when importing (Email, Company domain name).

The unique identifiers available for use when importing are:

• Email: the email address of a contact. This is required when importing contacts to avoid duplicates or to associate contacts with another object. If you don’t have contact email addresses, use the Record 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 importing companies to avoid duplicates or to associate companies with another object. If you don’t have company domain names, use the Record ID to update and associate existing company records.
• Record ID: a unique property value given to each record by HubSpot. If you export existing records from HubSpot, each record will have a Record ID. This is the default unique identifier for deals, tickets, appointments, courses, listings, services, activities, and custom objects, but can also be used as the unique identifier for contacts and companies if you don't have emails or company domain names. If Record ID is included in your import, it will supersede any other unique identifiers.
• Custom property that requires unique values: if you've created a property that requires unique values, you can use the property as a unique identifier in your import files. This is supported for contacts, companies, deals, tickets, appointments, courses, listings, services, and custom objects.

For contacts and companies, it's recommended to use their respective unique identifiers when importing (Email, Company domain name). This allows for maintaining data quality.

Example: use Record ID to update existing deals 

You want to update several properties for all existing deals in your pipeline. Export those deals and only include the properties you want to edit plus Record ID. Make the desired updates in the spreadsheet, leaving the Record ID column untouched. Perform a deal import and use Record ID as the unique identifier in the map columns part of the process.

Associations

You can also import to associate records with one another and add association labels to specify the relationship between records. This includes cross-object associations such as deal to contact or same-object associations such as contact to contact. 

Learn more about how to properly include associations in your import files.

Example: import a contact same-object association

Your business tracks manager to individual contributer (IC) relationships using the contact object. The managers already exist in HubSpot. Configure a single import file to contain the primary email of both contacts in separate columns (e.g., Manage email, IC email). The manager email property value should match the one already in HubSpot. Start a contact import, select the option to create same-object associations, configure the rest of the details, and finish the import. You can also use custom association labels to label the relationship.

Map columns to properties

Once you've uploaded your file to the import tool, there's a step in the import process when you'll be prompted to match the column headers in your file to HubSpot properties. Mapping correctly ensures that your data goes to the right place (i.e. the correct object and the correct property) when added to HubSpot.

For example, for a contacts file, you'd map the column First Name to the First Name contact property.

For a file associating multiple objects, you'd select the corresponding object and property for each column.

Import errors

If your import contains errors during the mapping process, you can manage certain errors to fix the data before it's added to your account. If there are errors following an import, you can review and troubleshoot the errors to add or update affected data.

Additional ways to update data in HubSpot

• For contacts and companies, you can turn on the setting to automatically create and associate companies with contacts based on the contact’s email domain. If you have contacts with email domains that are different from their companies' domains, or if you're importing other objects, follow the instructions to associate your records via import.
• If you have data in another system and want to set up a two-way sync, learn how to connect and use HubSpot data sync.