Set up import files

Before you import data into HubSpot, review the following limits and requirements. You can also access sample files or generate example files to get you started.

To learn more about the import tool, refer to this article. If your file is ready, learn how to import.

Technical requirements and 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.
• If you're importing an Excel file:
  • Contain data that stays under Excel's worksheet and workbook maximum limits.
  • Contain cells in Number format when importing date and time picker properties.

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. 

Formatting values

For each row of your import file, you can add values for the property columns. The formatting of a value depends on the property field type and goal of the import.

Format values based on property field type

Depending on the property field type, there are specific formatting requirements:

Additional contact emails or company domains

If you're importing contacts with more than one email address, include an Additional email addresses column with their secondary emails. If you're importing companies with more than one domain name, include an Additional domains column with their secondary domains. To include multiple emails or domains in a cell, separate the values with semi-colons (e.g., email@email.com; emailtwo@email.com).

If you're importing to create contacts or companies, you cannot set a new contact's Email or new company's Company domain name to an email or domain that's an existing additional email/domain for another record.

Blank cells

Deal collaborators

Product term and billing frequencies

If importing a Term property value, you can format the value in the Term column as a number in months (e.g., 10 for 10 months), 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 importing 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 to create records, and must be included as columns headers in your files. If you're updating records, you must include a unique identifier (e.g., Record ID, Email, Company domain name).

While not required, you can import additional properties for each object, including custom and default properties. Refer to the default properties for contacts, companies, deals, tickets, calls, emails, meetings, notes, and tasks. You can also view all properties and their values in your property settings.

• Contacts: at least one of First name, Last name, or Email.
• Companies: at least one of Name or Company Domain Name.
• Deals: if you're creating new deals, Deal name, Pipeline, and Deal stage.
• Tickets: if you're creating new tickets, Ticket name, Pipeline, and Ticket status.
• Appointments: Appointment Start. The appointment start should be formatted as a date-time property.
• Courses: Course Name.
• Listings: Name.
• Services: Name, Pipeline, and Pipeline Stage.
• Products: if you're creating products, Unit price and Name.

• 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: when importing line items with deals, the import will not update the deal amount. To 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. When importing new calls, it's also recommended to include Activity date.
• Emails: Email body and Email direction.
• Meetings: Meeting description, Meeting start time, and Meeting end time. When importing new meetings, it's also recommended to include Activity date. The start time, end time, and activity date values should be formatted as date-time properties.
• Notes: Note body.
• Tasks: Task title and Due date. The due date should be formatted as a date-time property.

Please note: while not required, it's recommended to include Activity date when importing new activities to specify the date and time an activity occurred. If you don't include this property, the Activity date values are automatically set to the date and time of the import.

Requirements to update existing records or avoid duplicates

To update existing 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, or use a custom property that requires unique values. 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).

Requirements to associate records

Import associations in one file

In one file, you can associate two or more records per row. Include information about associated records and/or activities in the same row and include a unique identifier for each object. 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.

If you're importing same object associations, there are additional requirements.

Import associations in two files

To associate records of two objects 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.

Same object associations

You can import one file to associate records of the same object in bulk. During the import process, you'll need to select a checkbox to include same object associations.

When setting up your file, include information about the associated records in the same row and include a unique identifier for each record. The following additional requirements are specific to same object imports:

• At least one record in a record pair must already exist in HubSpot before importing. For example, you can import a new contact and associate it with an existing contact, but you cannot import to create and associate two new contacts.
• When associating existing contacts/companies, you can only use the primary email/company domain as your unique identifier. Secondary emails or domains are not supported.
• If you're associating multiple records with one record, separate the records' unique identifier values by a semi-colon in the same cell (e.g., luke@lukesdiner.com; rory@yale.edu; sookie@dragonfly.com).

In the example file below, Rory and Jackson are new contacts being associated with unique labels to existing contacts, using their Email values as the unique identifier. Sookie is an existing contact being associated to two existing contacts with the same label. In the first row, the association label is part of a label pair, which means once the import is completed, the associated record will have the label Parent and Rory will have the paired label, Child.

Parent/child associations

To create child-parent company associations via import, learn more about importing child companies.

Custom association labels (Professional and Enterprise only)

To import association labels, include an Association label column. You must create the association labels in HubSpot prior to importing.

• To set a company association as primary, include the value Primary in the Association label column for that row.

• 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.
• If you're importing paired labels:
  • For cross-object associations, only include one of the labels in the Association label column. The labels will be assigned to the correct object during the import process.
  • For same object associations, the record in the Associated [unique identifier] column will receive the label added in the import process or included in the file's label column. The other record in the row will receive the other label in the pair.

Example files

At the beginning of the import process, you can generate an example file with the required properties for the selected objects and activities. If you'd like to review more examples with additional properties, refer to this article with sample files.