Set up your import files

Last updated: February 18, 2021

Applies to:

All products and plans

Format your import data correctly on your computer to prevent any errors when importing objects to HubSpot. Once you've set them up, learn how to import these files.

Requirements for all import files

  • The import file must be  .csv, .xlsx, or .xls file.
  • The import file should only have one sheet.
  • The import file should contain fewer than 250,000 rows and 1,000 columns.
  • The import file should be smaller than 150MB.
  • Include a header row in your file.
    • Each column header should correspond to a property that exists for the object being imported.
    • During the import process, HubSpot will match the column header to the property name, where possible, to map the property values to be updated. Otherwise, you can manually map your column headers to property values.
  • Import files for each object require the following properties:

    • Contacts: First name, or Last name, or Email.
    • Companies: Name or Company Domain Name.
    • 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.
  • To assign an owner to an object during the import, include a [Object] owner header and add the email address of the user to each row in that column.

Please note: users who are assigned a record through import will not receive a notification that they were assigned a new object.

  • For a file with multiple objects, ensure that the data in the rows match up to the correct header (e.g., rows with contact data should have data in columns that map to contact properties, and rows with deal data should have data in columns that map to deal properties).
  • If you’re importing data into multiple checkbox or single checkbox properties, learn how to format the values in your spreadsheet before importing into HubSpot. 

Requirements for importing products

  • To import products with a Term property value, format the value for products 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).
  • To import products with 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 fixed price type.

Example import files

Sample files of one object

The most straightforward import files contain one object only. Open the following files to see how they are formatted:

  • Contacts sample spreadsheet: CSV or XLSX
  • Companies sample spreadsheet: CSV or XLSX
  • Deals sample spreadsheet: CSV or XLSX
  • Tickets sample spreadsheet: CSV or XLSX
  • Products sample spreadsheet: CSV or XLSX

You can also test these import files out in your HubSpot account by importing them, then deleting the newly created test contacts.

Some of the properties included in these files are custom (i.e., they do not exist in your HubSpot account) so you may want to exclude them in your test import.

Sample files of multiple object

In some cases, your import file may contain more than one object. Open the following files to see how files with more than one object are formatted:

  • Contacts and companies sample spreadsheet: CSV or XLSX
    • When the contact's and company's data is in the same row, the two records will be associated upon import.
    • The "Company name" and "Annual Revenue" columns should be mapped to the Name property and Annual revenue property of the Company object, and not the properties of the Contact object.
    • Both the "Vendor type" and "Favorite Ice Cream Flavor" columns are custom properties. If you try importing this file, you can opt to not import these columns or create a custom property.
  • Companies and deals sample spreadsheet: CSV or XLSX
    • When the company's and deal's data is in the same row, the two records will be associated upon import.
    • The "Vendor type" column is custom. If you try importing this file, you can opt to not import this column or create a custom property.

Sample files of one object for association

View the files used in the example below. Both files must be imported together as part of the import process:

  • Contacts sample spreadsheet for association: CSV or XLSX
  • Deals sample spreadsheet for association: CSV or XLSX

Requirements for associating objects in import files

When importing two files for association:

  • You need to have one file per object. Currently, you cannot import product associations.
  • In each file, include a column with the same header.
  • To associate an object from the first file to an object from the second file, type the same string under the column for the two objects. The string can be anything, as long as they match.
  • You can use unique identifiers for existing records as this string for convenience. This includes:

Please note: the string used for association must be under 100 characters.

During the import, HubSpot will reference this column header and match the objects in each file by the data in this column. The matched objects will be associated.

For example, you can import new contacts and deals then associate them during the import.

  • Prepare two spreadsheets, one for contacts and one for deals. In each spreadsheet, create a Common field column. This column can be named anything, as long as they match in both files.
  • In your contact import file, enter a unique string under 100 characters for each contact in the Common field column.

  • In your deal import file, for each deal, in the Common field column, enter the unique string that corresponds to the contact you want to associate the deal with.

  • Save these spreadsheets to your computer.
  • Continue to import your files into HubSpot. The common field will match the contacts and the deals for association. For illustration, "Daphne" will be associated to the "Water heater" deal.

Another option is to use a unique identifier already in the files, such as email addresses. Because the email column is unique to each contact record in the file, adding the same column in the file containing the deal records can help associate the deal record to the appropriate contact.

Other important considerations

Existing HubSpot objects in the import file

If you import a file with information for existing objects, any existing information will be overwritten by new values you've imported. HubSpot checks for an existing object using:

Learn more about how HubSpot detects if an import contains existing objects.

If you don't want to overwrite an existing value for a property, you can either include the current value in the relevant column or leave the cell blank. HubSpot will not overwrite a property value unless there is a new value present in the file.

If you want to clear a property value in an existing object, you can only do so using a workflow (Professional and Enterprise users only). Blank values will be ignored.

Duplicate objects in the same file

If the import file has duplicate objects, HubSpot will import the information in any one of the duplicate rows to the record. To ensure accurate information is added to your records, ensure that there are no rows with duplicate email addresses or Company domain name property values in your import file.

Automatic association between contacts and companies

If the Automatically create and associate companies with contacts setting is enabled, contacts will be automatically associated with company records by matching the contact's email address domain to the Company Domain Name property in the company record.

Unmatched columns in the import file

If your spreadsheet has a column header that does not correspond to an existing property in HubSpot, you can select an existing property or create a new custom property for it. 

Special characters in the import file

Excel does not always properly save special characters when saving in .csv file format. You can import your list into Google Sheets to resolve this.

How to Import Your Contacts into HubSpot CRM