Deduplicate records in HubSpot
Last updated: November 27, 2023
HubSpot automatically deduplicates contacts using email addresses, and companies using domain names. Record IDs can also be used to deduplicate contacts, companies, deals, tickets, products, and custom objects. To deduplicate via import, you can include Record IDs or custom properties that require unique values in your import file. Users in a Professional or Enterprise accounts can also manually manage possible duplicates by using the duplicate management tool.
Automatic deduplication in HubSpot
HubSpot deduplicates objects that are created in the CRM (e.g., imports, forms submissions) in the following ways:
- Deduplicate contacts by usertoken
- Deduplicate contacts by email address
- Deduplicate companies by company domain name
- Deduplicate records by record ID
- Deduplicate records by custom unique value properties
Deduplicate contacts by usertoken
If two form submissions come from the same browser and computer, the submissions will be merged into one record because HubSpot will detect the same user token for both submissions. In this case, the following will happen:
- The information from the second form submission will overwrite the information from the first submission because they have the same cookie stored in their browser.
- If the email address from the second submission doesn't already exist as a contact in HubSpot, the email address will overwrite the existing email address for the contact.
- If the contact submits the form using one of their secondary emails in HubSpot, the secondary email will replace the primary email following the submission.
If you want each form submission from the same browser to create a new contact, you can enable the Always create new contact for new email setting in your form options.
- If a form is submitted via a meetings link, a unique email address will always create a new contact, regardless of if an existing contact has a matching user token. In this case, the existing contact's email address will not be overwritten by the new email address.
- If a form is submitted via a non-HubSpot form, it is not possible to de-duplicate by usertoken or email. All non-HubSpot form submissions from the same browser and device will be associated with a single contact.
Deduplicate contacts by email address
When a new contact is added, HubSpot will look for a matching value in the Email property.
- If you try to manually create a contact with the same email address as an existing contact, HubSpot will alert you that a contact already exists, and you will not be able to add the additional contact.
- When added via form submissions, if a contact already exists in your account with the same email address, the new contact information will be added to the existing contact record. If the contact submits a form with their secondary email address, the email address will overwrite the existing email address for the contact. If you want each form submission from the same browser to create a new contact, you can enable the Always create new contact for new email setting in your form options.
- When added via import:
- If a contact already exists in your account with the same email address, the new contact information will be added to the existing contact record. For example, if you import a list of contacts that includes "email@example.com," and an existing contact in your HubSpot account has the email "firstname.lastname@example.org," the imported information will be added to that existing contact record.
- If you're using a contact's secondary email in HubSpot as their unique identifier in an import, 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 don't want the secondary email to overwrite the primary, do not also include the Record ID column in your file.
- If you do not include the Email property in your import, each row of your import file will be imported as a new contact record.
- If multiple records already exist with the same email address as a contact you're importing, you'll receive an import error and that contact will not be imported.
Deduplicate companies by company domainWhen a new company is added, HubSpot looks at the primary value for the Company domain name property to deduplicate companies. Secondary domains included as additional domains on a record are not used to deduplicate companies. Learn how to set a domain as primary.
- If you try to manually create a company with the same domain name as an existing company's primary domain, HubSpot will alert you that a company already exists.
- When added via import, the Company domain name will be used to deduplicate companies unless you've selected to use a custom property that requires unique values as the unique identifier instead. If you use a custom property that requires unique values, your file can include duplicate company domain names.
- If a company already exists in your account with the same domain name or custom unique ID property value, the new company information will be added to the existing company record.
- If multiple companies already exist with the same domain name or custom unique ID property value, you'll receive an import error and that company will not be imported.
- If you do not include the Company domain name or another custom unique ID property in your import, each row of your import file will be imported as a new company record.
Please note: companies created through API will not be deduplicated by the Company domain name property.
Deduplicate records by Record ID
When you want to import contact, company, deal, ticket, product, or custom object records, you can use a unique Record ID to match up these records with existing records in HubSpot. This Record ID can be used to deduplicate records during the import process, or to search for a specific record in HubSpot.
- To get the Record IDs, export your records or view a specific object's value for their Record ID.
- Include a Record ID column in your file when you import your records into HubSpot. If you include the Record ID column in your file, any rows without a value for Record ID will create new records.
- During the import, you'll be prompted to match the column with Record ID in the Import as dropdown menu.
Please note: if you only use Record IDs to deduplicate, it is recommended to check for existing records in HubSpot before you import an external file. To do this, you can:
- Export your records with their Record IDs and at least one property that is included in the external file.
- Use the VLOOKUP function to cross-reference the information in the new file with the exported file. Learn more about using VLOOKUP in Excel or Google Sheets.
- Assign the correct Record ID values to any duplicate you've identified.
- Separate the data into two import files; one file with existing records and their Record IDs, and another file containing all new records.
- Import the files. The file with the Record IDs will update your existing records, and the other file will create new records.
Deduplicate records by custom unique value properties
For contacts, companies, deals, tickets, and custom objects, you can create up to ten custom properties that require unique values. When a property requires unique values, users will be unable to enter the same value for multiple records.
For example, your company creates an order number for each online purchase. You can set up an Order number property that requires a unique number for each deal. If a user tries to create or edit a deal using an existing Order number value, they'll be notified that the number is already in use and will be unable to save the deal.
The following behavior is expected for unique value properties:
- Unique values are supported when manually creating or editing a record in HubSpot, and when creating, updating, or associating companies, deals, tickets, and custom objects via import. You cannot currently use contact unique value properties in imports.
- Unique values are not currently supported in forms. If your goal is to update or associate existing records via form submissions, it's recommended to use the default deduplication properties instead (i.e. Email, Domain name, Record ID).
- If you create a unique value property for contacts, when visitors are converted to a contact record, any visitor property values that violate the unique property requirements will be cleared. Learn more about identifying visitors.
Manually deduplicate contacts and companies (Professional and Enterprise only)
You can also deduplicate contacts and companies in your HubSpot account using the duplicate management tool. If your account has an Operations Hub Professional or Enterprise subscription, you can deduplicate records in bulk, and view an overview of duplicate record data in the data quality command center.
To use the duplicate management tool, users must have Data quality tools access and Edit access set to Everything for contacts and/or companies (i.e. access to contacts to manage contact duplicates, companies to manage company duplicates, and both to access all duplicates).
The duplicate management tool identifies duplicates by comparing the records' values for the following properties:
- Contacts: First Name, Last Name, Email address, IP country, Phone number, Zip Code, and Company Name.
- Companies: Company Domain Name, Company Name, Country/Region, Phone Number, and Industry.
- In your HubSpot account, navigate to contacts or companies:
- Contacts: In your HubSpot account, navigate to Contacts > Contacts.
- Companies: In your HubSpot account, navigate to Contacts > Companies.
- In the upper right, click the Actions dropdown menu and select Manage duplicates.
- View a list of duplicate contact or company pairs for your review. You can also view when the next calculation will occur.
Please note: if HubSpot displays a parent company as a duplicate of a child company, you will not be able to review or dismiss this pair as a duplicate. You must remove the parent-child relationship before you can merge them.
- To change which properties are displayed when comparing records, above the table, click Select properties to review. This option only appears if there are potential duplicates currently included in the list.
- To remove a displayed property, click X next to it in the Selected properties section.
- To display a property, click the checkbox next to the property.
- Click Apply once you've selected the properties.
Please note: the properties you select are not used as criteria to identify duplicate records. The properties are displayed to provide additional context when comparing records identified by the duplicate management tool.
- To compare a single pair of possible duplicates, click Review next to a pair of contacts or companies.
- In the dialog box, you can compare the record properties and analyze the record to keep. Select the contact or company you want to keep, then click Merge. Learn more about merging contacts or companies in HubSpot.
- If the two records are not duplicates, in the dialog box, click Cancel. In the table, click Reject to remove this identified pair from the Manage duplicates dashboard. Rejected suggestions will not appear in the duplicates tool moving forward.
- To merge duplicate records or reject suggestions in bulk (Operations Hub Professional and Enterprise only), select the checkboxes next to the records.
- To reject the suggested pair, click Reject at the top of the table. The records will be removed from the dashboard and will not appear as a suggestion moving forward. If a record from a previously rejected suggestion is merged into another record, it could reappear in the duplicates tool.
- To compare the records, click Review at the top of the table.
- In the dialog box, click the Merge criteria dropdown menu and select the criterion that decides how the records are merged:
- Most recent engagement: all selected records will be merged into the record with the most recent value for the Last Engagement date property. Engagements that impact this property include interactions with website pages, forms, documents, meetings link, or tracked one-to-one emails.
- Oldest engagement: all selected records will be merged into the record with the oldest value for the Last Engagement date property.
- Created first: all selected records will be merged into the oldest record based on the Create date property.
- Created last: all selected records will be merged into the newest record based on the Create date property.
- Most recently updated: all selected records will be merged into the record with the most recent property value update. All properties, including hidden internal HubSpot properties, are evaluated.
- Click Merge all.