Automatically Merge Duplicate HubSpot Contacts (Video + n8n Workflow)

This first step lets you manually test the workflow. Using n8n’s Manual Trigger module, you can run the scenario on demand to verify that everything works before automating it in production.

The manual trigger is especially useful for testing each step in real-time and diagnosing any issues. Once your tests are validated, you can replace this trigger with an automated one (e.g., cron, webhook…) if needed.

To start: click "Execute Workflow" in n8n to begin the process.

This step uses the HubSpot module to fetch all contacts stored in your CRM. The goal is to build a full dataset to analyze and detect duplicates based on your chosen unique identifier (e.g., LinkedIn Profile ID).

We use the Get All option to retrieve all records at once, allowing you to process every contact automatically without any specific limit.

This step allows you to centralize all contact records so they can be processed one by one in the next steps.

This step uses the SplitInBatches module to process each contact one by one. It helps prevent API overload and gives you precise control over individual contact handling.

The batch is configured with a size of 1, meaning each workflow execution processes a single contact before moving on to the next.

This setup ensures smooth and safe execution even when dealing with a large volume of contacts.

To avoid API overload and comply with HubSpot rate limits, this step uses a Wait module to insert a 1-second delay between each contact processing.

This step is essential if you're handling a high volume of contacts—it prevents errors like "429 Too Many Requests" during consecutive HubSpot API calls.

Thanks to this short pause, the workflow remains stable and API-compliant, even when running across hundreds or thousands of contacts.

This step is crucial: it uses an IF module to verify whether the current contact has a LinkedIn Profile ID. This field is essential for accurately detecting duplicates.

If the contact doesn’t have this field filled in, the workflow skips it and moves to the next one, avoiding errors or unnecessary lookups.

This step helps secure the workflow by ensuring that only eligible contacts (those with a LinkedIn ID) are analyzed.

This step is essential: it identifies all duplicate contacts based on their LinkedIn Profile ID. To do this, we use the native HubSpot – Search module, which allows you to search contacts by a custom property.

Why this approach? Unlike company searches that require a custom API call, here we can use the native n8n module directly, as it supports searching contacts by custom property.

The module queries the HubSpot API using the internal endpoint and limits the results to 2, which is enough to confirm a duplicate.

{
  "propertyName": "linkedin_profile_id|number",
  "value": "={{ $('Loop Contacts One by One').item.json.properties.linkedin_profile_id.value }}"
}

This query searches for all contacts whose LinkedIn Profile ID matches the one from the current contact being processed. The response includes the key data of the contact to be merged.

Why a limit of 2? This checks whether there are at least two contacts with the same LinkedIn Profile ID. If that’s the case, a duplicate is detected and the workflow proceeds to the next step to merge them.

This step uses a Code module to analyze the results returned by the HubSpot search. Its role is twofold: count the number of results and extract the IDs of the contacts to be merged.

The code checks whether at least 2 contacts were found. If so, it extracts:

• primaryObjectId: the ID of the first contact (to be kept after the merge)
• objectIdToMerge: the ID of the second contact (to be merged and removed)

This code also adds a safeguard: if fewer than 2 contacts are found, it returns an info message stating that no merge will be performed in this cycle.

This step prepares all the necessary data for the final merge API call.

This step uses an IF module to check the number of results found during the duplicate search. The goal is to confirm whether at least two contacts exist with the same LinkedIn Profile ID.

If the number of results is less than or equal to 1, it means no duplicate was detected, and the workflow automatically moves on to the next contact without attempting a merge.

This step helps avoid unnecessary API calls when the search results include only one contact (or none), ensuring better performance and improved reliability.

This step uses an IF module to make sure that the two contacts to be merged have different IDs. This is a critical safeguard—HubSpot does not allow merging a contact with itself, and skipping this check could trigger an error.

This condition prevents unnecessary API errors by blocking the merge attempt if primaryObjectId and objectIdToMerge are the same.

This step helps fully secure the process before the final API call is made.