Skip to content

Import and associate multiple objects

Last updated: January 20, 2023

Available with any of the following subscriptions, except where noted:

All products and plans

You can import files to create, update, or associate HubSpot records in bulk. You can also import to create new activities in bulk. This article explains how to import and associate multiple types of records, also known as objects, as well as new activities associated with records.

When importing multiple objects or activities, you can create, update, or associate the following:

  • CRM objects: contacts, companies, deals, tickets, and defined custom objects.
  • Activities: calls, emails, meetings, notes, or tasks associated with other objects.  You cannot update existing activities via import. Learn more about importing activities.
  • New line items associated with deals and existing products. You cannot update existing line items via import.
  • Association labels to describe the relationships between your records.

You can also import a single object in HubSpot. 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 instead of importing.

Before you get started

Before you start an import, set up your import files and confirm you have all the required fields for your multiple object import.

To associate contacts and companies, you can also 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.

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.

Please note: when importing in one file, you must include a unique identifier to avoid duplicates and properly associate records. For example, when importing multiple contacts who work for the same company, if you include Company domain name as the company’s unique identifier, one company record will be created and the contacts will be associated with that record. However, if you don’t include Company domain name, HubSpot will create duplicate company records, and each record will be associated with only one contact. If you don't have domain names for your companies, import companies in one file, export the records, then use the Record ID as your unique identifier.


Once your file is set up correctly:
  • Navigate to your records:
    • Contacts: In your HubSpot account, navigate to Contacts > Contacts.
    • Companies: In your HubSpot account, navigate to Contacts > Companies.
    • Deals: In your HubSpot account, navigate to Sales > Deals.
    • Tickets: In your HubSpot account, navigate to Service > Tickets.
    • Custom objects: In your HubSpot account, navigate to Contacts > [Custom object]. If your account has more than one custom object, hover over Custom Objects, then select the custom object you want to view.
  • In the upper right, click Import.

  • Click Start an import.

  • Select File from computer, then in the bottom right, click Next or press Enter.

  • Select One file, and click Next or press Enter.

  • Select Multiple objects, and click Next or press Enter.

  • Select the objects and activities in your import file. Then, click Next or press Enter.

  • Click choose a file, then select your import file.

upload-your-files-multiple-objects-one-file

  • If you're importing data in a language other than your default language, click the dropdown menu and select the language of your file's column headers. Selecting the correct language enables HubSpot to better match your column headers to existing default properties. If there is no match in your selected language, HubSpot will search for an English property to match.
  • Click Next or press Enter.
  • On the Map columns in your file to [object] properties screen, HubSpot will automatically map the columns in your file to properties in your selected objects.

mapping-page-comparison

  • You'll see a preview of the first three rows from your spreadsheet in the Preview Information column.
    • If there are no errors detected in the first three rows of a column, there will be a success checkmark in the Mapped column.
    • If certain errors are detected in the first three rows of a column, there will be an exclamation exclamation icon in the Mapped column. Hover over the icon to view the error, and click Fix import errors to learn how you can resolve the error.
  • If any columns were matched to the wrong object's properties, click the dropdown menu in the Import as column then select [Object/Activity] properties for the correct object.
  • If any columns do not match an existing property, click the corresponding dropdown menu in the HubSpot Property column:
    • To map the column to an existing property, select an existing property.

    • To set up a new custom property (objects only), click Create a new property, then set up your new property in the right panel. The data in the column will now be mapped to this new custom property.
  • To import association labels, click the dropdown menu in the Import as column, then select Association label. When importing two objects, the HubSpot property column will automatically populate the object relationship for the objects you're importing (e.g., Contact and Company). If you're importing more than two objects, select the two objects whose relationship the association labels describe.

association-label-import

Please note: importing a new association label will not overwrite an existing association label. The imported label will be added to the record as an additional association label. Learn how to manually remove an association label from a record.

  • To skip importing data from an individual row, click the dropdown menu in the Import as column, then select Don't import column.
  • To skip importing data from all unmapped rows, select the Don't import data in unmapped columns checkbox in the bottom right.
  • If you're using the Record ID to associate, update, or avoid duplicate records, click the dropdown menu in the Import as column, then select Record ID - [Objects] for the correct object. Existing records will be updated by the import based on the Record ID. If a row in your file doesn't contain a value for Record ID, a new record will be created.

Please note: when associating line items with existing products, there is not a Record ID - Products option. Instead, select Line item properties in the Import as column and Product ID in the HubSpot property column.

select-record-id-multiple-objects

Please note: if you're using an existing contact's secondary email in HubSpot as their unique identifier, the secondary email will not replace the primary email if you do not include the Record ID column in your file. If you include both the secondary email and Record ID as columns in your file, the secondary email will replace the primary email when imported.

  • If you’re using Email or Company domain name to deduplicate your contact or company records:
    • To prevent the import from overwriting records’ individual properties, select the Don’t overwrite existing value checkbox.
    • To prevent the import from overwriting all properties included in the import, select the checkbox at the top of the table. 
    • With the checkbox selected, the import will not update that property for any records that have the value. Any new records or existing records with no value for that property will be updated.

dont-overwrite-existing-value-import

  • Once all columns are mapped to a property or set to Don't import column, click Next or press Enter.
  • On the details screen:

    • Enter an Import name.

    • If you're importing contacts:

    • If you're importing a file with a date property, use the Date format dropdown menu to confirm how the date values in your spreadsheet are formatted.
    • If you're importing a file with a number property, use the Number format dropdown menu to confirm which country's number format to use for your data.
  • Once you've set the options for your import, click Finish import in the bottom right.

You can view, analyze, and complete actions with your previous imports. Learn how to create a list, review import errors, or view and delete imported records.

Import multiple objects in two files

To import and associate multiple objects in two files, you must include a common column in both files to identify which records will be associated.

Once your files are set up correctly:

  • Navigate to your records:
    • Contacts: In your HubSpot account, navigate to Contacts > Contacts.
    • Companies: In your HubSpot account, navigate to Contacts > Companies.
    • Deals: In your HubSpot account, navigate to Sales > Deals.
    • Tickets: In your HubSpot account, navigate to Service > Tickets.
    • Custom objects: In your HubSpot account, navigate to Contacts > [Custom object]. If your account has more than one custom object, hover over Custom Objects, then select the custom object you want to view.
  • Click Start an import.

  • Select File from computer, then click Next or press Enter.

  • Select Multiple files with associations, then click Next or press Enter.

  • Select the two objects or objects and activities to associate via import, then click Next or press Enter.

  • For each object, click choose a file, then select your import file.

upload-your-files-multiple-objects-two-files

  • If you're importing data in a language other than your default language, click the dropdown menu and select the language of both your files' column headers. Selecting the correct language enables HubSpot to better match your column headers to existing default properties. If there is no match in your selected language, HubSpot will search for an English property to match.
  • Click Next or press Enter.

  • Click the Common column headers found in your files dropdown menu and select the name of the common column that appears in both of your files.

  • In the Which object is [common column] the unique key for? dropdown menu, select the object that has a unique value for each row of the common column. For example, if you're importing contacts and companies and are using a unique value in each company row, select Company.

    unique-key
  • Click Next or press Enter.

  • On the Map columns in your file to [object] properties screen, HubSpot will automatically map the columns in your file to the selected object's or activity's properties in HubSpot.

mapping-page-comparison

  • You'll see a preview of the first three rows from your spreadsheet in the Preview Information column.
    • If there are no errors detected in the first three rows of a column, there will be a success checkmark in the Mapped column.
    • If certain errors are detected in the first three rows of a column, there will be an exclamation exclamation icon in the Mapped column. Hover over the icon to view the error, and click Fix import errors to learn how you can resolve the error.
  • If any columns do not match an existing property, click the dropdown menu in the HubSpot Property column:

    • To map the column to an existing property, select an existing property.

    • To set up a new custom property, click Create a new property, then set up your new property in the right panel. The data in the column will now be mapped to this new custom property.

  • To import association labels, click the dropdown menu in the Import as column, then select Association label. When importing two objects, the HubSpot property column will automatically populate the object relationship for the objects you're importing (e.g., Contact and Company). If you're importing more than two objects, select the two objects whose relationship the association labels describe.

association-label-import

Please note: importing a new association label will not overwrite an existing association label. The imported label will be added to the record as an additional association label. Learn how to manually remove an association label from a record.


  • To skip importing data from an individual row, click the dropdown menu in the Import as column, then select Don't import column.
  • To skip importing data from all unmapped rows, select the Don't import data in unmapped columns checkbox in the bottom right.

Please note: when associating line items with existing products, there is not a Record ID option for products. Instead, for your line items file, select Line item properties in the Import as column and Product ID in the HubSpot property column.

select-record-id-mapping-page

Please note: if you're using an existing contact's secondary email in HubSpot as their unique identifier, the secondary email will not replace the primary email as long as you do not include the Record ID column in your file. If you include both the secondary email and Record ID as columns in your file, the secondary email will replace the primary email when imported.


  • If you’re using Email or Company domain name to deduplicate your contact or company records:
    • To prevent the import from overwriting records’ individual properties, select the Don’t overwrite existing value checkbox.
    • To prevent the import from overwriting all properties included in the import, select the checkbox at the top of the table. 
    • With the checkbox selected, the import will not update that property for any records that have the value. Any new records or existing records with no value for that property will be updated.

dont-overwrite-existing-value-import

  • Click Next or press Enter, then map the columns in the second spreadsheet.

  • Once all columns are mapped to a property or set to Don't import column for both files, click Next or press Enter.

  • On the Details screen:

    • Enter an Import name.

    • If you're importing contacts:

    • If you're importing a file with a date property, use the Date format dropdown menu to confirm how the date values in your spreadsheet are formatted.

    • If you're importing a file with a number property, use the Number format dropdown menu to confirm which country's number format to use for your data.
  • Click Finish import.

You can view, analyze, and complete actions with your previous imports. Learn how to create a list, review import errors, or view and delete imported records.

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.