Set up your import files

Whether HubSpot is your first CRM or you’re moving from another system, importing helps you create records and activities, 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.

Glossary

• 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're 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'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. Activities include calls, emails, meetings, notes, and tasks. You can create new activities via import, but cannot update existing activities. Calls and tasks can be imported on their own, but emails, meetings, and notes must be imported and associated with a CRM object.

• 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.

  Example file

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 avoid creating duplicate records (e.g., two records for “Tom Smith”) and to associate different records (e.g., import “Tom Smith” and associate him with his company “Smith Inc.”). 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 a required column when importing and associating existing deals, tickets, or custom objects with another object, but can also be used as the unique identifier for contacts and companies if you don't have emails or company domain names.
• Custom property that requires unique values (companies, deals, tickets, and custom objects only): if you've created a property that requires unique values, you can use the property as a unique identifier in your import files.
• Association label (Professional and Enterprise only): a value that specifies the relationship between records. Once you've created association labels, you can import them with your records.

• Map columns: a step in the import process, when you'll be prompted to match the column headers in your file to HubSpot properties.

For 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'll map columns to HubSpot properties (First Name column to the First Name HubSpot property).

Example file

Mapping columns to properties

File requirements and technical limits

• Be a .csv, .xlsx, or .xls file.
• Have only one sheet.
• Include a header row in which each column header corresponds to a property in HubSpot. The column headers can be organized in any order without affecting the import. You can confirm if a default property already exists to match your header or create a custom property prior to importing. Learn more about property requirements.
• Contain less than 1000 columns.
• 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.
• Only contain currency data formatted for USD using decimals (e.g. 123.45). 

There are additional technical limits for the import tool depending on your HubSpot subscription. These limits include the size and row limits of an import file, as well as how many files and rows you can import per day.

• If you're using HubSpot's free tools, you can:
  • Import files up to 20MB.
  • Complete up to 50 imports per day.
  • Import up to 500,000 rows per day. If you import a file containing more than 500,000 rows, it will take multiple days to complete.
• If your account has a Starter, Professional, or Enterprise subscription, you can:
  • Import files up to 512 MB.
  • Complete up to 500 imports per day.
  • Import up to 10,000,000 rows per day, with a limit of 1,048,576 rows per file. If you're importing via the imports API, you can import up to 80,000,000 rows per day.

These limits apply to a rolling 24-hour period and do not reset at a specific time of day. Learn more about your HubSpot subscription and its limitations. 

Property requirements

Formatting property values

The following formatting rules are required to properly import your data:

• For the contact properties Phone number and Mobile phone number, to import and automatically format the phone number based on country code, format as +[country code][number]. If there is an extension, add ext[number]. For example, a phone number with a United States country code would look like +11234567890 ext123.

• For properties containing a price, you must use one of HubSpot's accepted currencies. The list of accepted currencies and their currency codes can be found in the Currency tab of your account default settings.
• The import tool ignores blank cells in a spreadsheet, so when importing new property data, leave cells blank for records without a value for the property. If an existing record already has a value for the property within HubSpot, blank cells will not clear the existing property value. To clear existing property values in bulk, you can manually edit the values or use the Clear property value workflow action.
• To assign an owner to a record or activity during the import:
  • For objects, include a [Object] owner header. For activities, include an Activity assigned to header.
  • Add the name or 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 or activity.
• For properties containing a date, to format a value for this property:
  
  • Valid date formats include mm/dd/yyyy (10/28/2020), dd/mm/yyyy (28/10/2020) or, yyyy-mm-dd (2020-10-28).
  • For date-time properties, to include a time, add the timestamp as hh:mm (28/10/2020 14:30). By default, the import tool uses a 24-hour clock. To specify a 12-hour clock, add AM or PM to the timestamp (10/28/2020 2:30 PM). If you don't include a timestamp, the time is set to midnight by default.

Please note: if you're importing a default HubSpot date property (e.g., Close date), your values must be formatted as a UNIX timestamp in milliseconds. 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.

• Depending on the property field type, there are other specific formatting requirements:
  • For custom number, text, or date picker properties, if you've set validation rules, your imported values must follow the rules or they will not be imported.

• • For enumeration property types, the values in your import file must match either the label or the internal value of the property's defined options. For HubSpot default enumeration properties (e.g., Lifecycle stage, Industry), the values must match the internal value or the label in English.
  • Learn more about 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.

Required properties

Depending on which objects or activities you're importing, the following properties are required, and must be included as columns headers in your files:

• Contacts: at least one of First name, Last name, Email, or for existing contacts, Record ID.
• Companies: at least one of Name, Company Domain Name, or for existing companies, Record ID.
• Deals: if you're creating new deals, Deal name, Pipeline, and Deal stage. For existing deals, Record ID. 
• Tickets: if you're creating new tickets, Ticket name, Pipeline, and Ticket status. For existing tickets, Record ID. 
• Products: Unit price and Name, or for existing products,Record ID.

• Line items: Name, Quantity, Price, and the associated deals' Record ID or Deal name. Include the product's Product ID if you're also associating the line item with a product, which will be mapped as a line item property during the import.

Please note: via import, you can import to create new line items, but cannot update existing line items. When importing line items with deals, the import will not update the deal amount. To update existing line items or update the associated deal amount, you can manually edit the line items or associate the line items with a deal in HubSpot.

• Calls: Call notes (a text field that describes or provides context about the call).
• Emails: Email body (the text body of the email) and Email direction (eitherIncoming or Outgoing).
• Meetings: Meeting description (a text field to describe the meeting), Meeting start time, and Meeting end time. The start and end time values should be formatted as date-time properties.
• Notes: Note body (the text body of the note).
• Tasks: Task title (the name of the task) and Due date. The due date should be formatted as a date-time property.

Additional properties

Additional properties are not required, but can also be imported into HubSpot to add or update data in bulk. You can import the following additional properties:

• HubSpot default contact, company, deal, and ticket properties, excluding certain automatically set properties that cannot be edited. Learn more about default contact, company, deal, and ticket properties.
• Any custom properties you've created for contacts, companies, deals, tickets, or custom objects.
• For all activities, you can import the following:
  • Activity assigned to: the owner of the activity. The value for this property must be either the user's name in HubSpot, or the user's email address. 
  • Activity date: the date and time the activity occurred. This should be formatted as a date-time property. If you import new activities and don't include this property, the Activity date values are automatically set to the date and time the activities were created.
• Call properties:
  
  • Call direction: the direction of the call, either Inbound or Outbound.
  • Call outcome: the outcome of the call. The options are set in your call and meeting outcome settings.
  • Call source: the source of the call. Options include VoIP, Zoom, or Integrations platform.
  • Call status: the status or outcome of the call. Options include Busy, Canceled, Completed, Connecting, Failed, In progress, Missed, No answer, Queued, or Ringing.

• • Call title: the name of the call.
  • Call type: the type of call. The options are set in your call and meeting type settings.

• • Recording URL: a URL to access the call's recording.
  • Transcript available: indicates if the call has a transcript, either TRUE or FALSE.
• Email properties:
  
  • Email subject: the subject line of the email.
  • Email send status: the status of the email. Options include Bounced, Failed, Scheduled, Sending, or Sent.

• Meeting properties:

• • Internal meeting notes: a text field to add notes about the meeting.
  • Location type: the type of location where the meeting was hosted. Options include Phone Call, Address, or Video Conference.
  • Meeting location: the name of the meeting's location.
  • Meeting name: a name for the meeting.

• • Meeting outcome: the meeting's outcome. The options are set in your call and meeting outcome settings.
  • Meeting type: the type of meeting. The options are set in your call and meeting type settings.
• Task properties:
  
  • Notes: a text field to add notes about the task.
  • Priority: the priority assigned to the task. Options include Low, Medium, or High.
  • Task type: the type of task. Options include Call, Email, or To-Do. If you don't set a type during import, the task will be set to To-Do by default. 
  • Task Status: the status of the task. Options include Completed, Deferred, In Progress, Not started, or Waiting.

Association and deduplication requirements

• To import and associate multiple objects in one file, include information about associated records and/or activities in the same row. In two files, use a common column to connect the records in each file. You can refer to the example files for more help importing and associating records.
• To update existing records, associate records, and avoid duplicate records, your files must include a unique identifier property for each object. For all objects, you can export existing records and use the Record ID as a unique identifier. For contacts, you can also use Email. For companies, you can also use Company domain name.
  • If you're importing multiple objects and are including Record IDs, it is recommended to differentiate the file column headers to match the ID with the correct object (e.g., one column called Record ID - Contacts and another called Record ID - Companies).
  • 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 Record ID column in your file, the secondary email will not replace the primary email. However, if you include both the secondary email and Record ID as columns in your file, the secondary email will replace the primary email.

• To associate one record with multiple activities or records of another object, include the record's unique identifier in multiple rows for each record you want to associate. For example, Luke Danes is a manager at Luke's Diner, but a contractor at The Dragonfly Inn. To associate him with both companies, you'd need to include two rows for Luke Danes with the columns Email (or Record ID), and Company domain name (or Record ID) for each company.

Please note: if you don't include unique identifiers (e.g., Email, Company domain name, Record ID), the import will create duplicate records instead of associating each to the same record.

• To import association labels (Professional and Enterprise only), include an Association label column. You must create the association labels in HubSpot prior to importing.
  • To set multiple labels to describe the relationship between two records, you can include multiple association label values in one cell, separated by a semicolon (e.g., Manager; Billing contact).
  • If you're importing association labels in a multiple file import, you need to include the Association label column and a unique identifier for the object you're associating in the same file.
• To create child-parent company associations via import, include a Parent company column in your import file with the parent companies' Record ID values. Learn more about importing child companies.

Sample import files

The following files include the required column headers for each object or activity, 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.

One object or activity

• 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
• Tasks sample spreadsheet: XLSX
• Calls sample spreadsheet: XLSX

Once your file is ready, learn how to import one object or activity into HubSpot.

Please note: products can only be imported in a single object import. You can associate an existing product to a line item, or manually associate a product to a deal or quote.

Multiple objects with associations

You can import and associate multiple objects, or objects and activities, together in one file or in two separate files, where each file represents one object/activity.

Import multiple objects in one file

To import and associate multiple objects/activities in one file, include the records/activities 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 or activities by replacing the column headers.

• Contacts and companies sample spreadsheet:  XLSX or CSV.
• Contacts and companies with association labels sample spreadsheet: XLXS 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
• Deals and new line items sample spreadsheet (with associated products) : XLSX or CSV. When importing in one file, you can only import one line item per deal.
• Calls and contacts sample spreadsheet: CSV
• Notes and tickets sample spreadsheet: CSV
• Tasks and existing deals sample spreadsheet: CSV
• Emails and existing contacts sample spreadsheet: CSV

Once your file is ready, learn how to import and associate multiple objects or activities into HubSpot.

Import multiple objects in two files

When importing and associating in two files, each file represents one object or activity. You can only import two objects or one object and one activity in a two file import. To import more than two objects/activities, you can import in one file.

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:

• Companies sample spreadsheet: XLSX or CSV.

• Contacts sample spreadsheet: XLSX or CSV.

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.

Additional examples include:

• Deals and companies with association labels in two files: in these sample files, Company name is the unique key for the Company object.
  • Deals sample spreadsheet: XLSX or CSV.
  • Companies sample spreadsheet: XLSX or CSV.
• Deals and new line items in two files: in these sample files, Deal name is the unique key for the Deal object. When importing in two files, you can import multiple line items per deal.
  • Deals sample spreadsheet: XLSX or CSV.
  • Line items sample spreadsheet (with associated products): XLSX or CSV.
• Calls and contacts in two files: in these files, Email is the common column and unique key for contacts.
  • Calls sample spreadsheet: CSV.
  • Contacts sample spreadsheet: CSV.

Once your files are ready, learn how to import and associate multiple objects or activities into HubSpot.