Skip to main content
Default matches HubSpot contacts inside a workflow. Before a form fill, API call, or webhook creates a contact, a Match Record node looks for a Contact with the same email. When one exists, the workflow works with that contact and leaves its owner alone. When none exists, the workflow picks an owner and creates the contact with Create Record. Matching is built from workflow nodes, so each rule can be tested and each decision shows in the run logs. The nodes are documented in CRM nodes. For Salesforce, see Salesforce contact matching.

​
How HubSpot contact matching works in Default

A contact intake workflow in Default runs these steps:
  1. A trigger starts the run with the person’s email. Use Form Submission, API, or Incoming Webhook. See Triggers.
  2. Match Record looks for the Contact. Set CRM to HubSpot and Record to Contact, and compare Email with the email from the trigger.
  3. Match: the person is already a contact. Later nodes use the contact’s ID and properties, such as Contact owner. The contact keeps its owner.
  4. No Match: create the contact. A Round-Robin node picks an owner, and Create Record creates the contact with that owner.
  5. Link the company. Find the contact’s Company and associate them. See HubSpot contact-to-company matching.

​
Why Match Record runs before Create Record in HubSpot

HubSpot’s Create Record has no Update on conflict option. It always sends a create request, so the workflow needs Match Record first to find a contact that already exists. HubSpot also refuses a second record with a value that must be unique, such as a contact’s email. When HubSpot’s rejection says that another record already has that value, Create Record does this:
  • It continues with the existing contact’s ID when HubSpot’s message names that ID, so later nodes can still use it. When the message names no ID, the step’s ID is empty and the warning says that creation was skipped. If later nodes need the ID, add a Multi-Branch after Create Record that checks whether its ID is empty, and on that branch find the contact with a Match Record on Email.
  • It logs a warning that the contact already exists, and the run counts the step as an error.
  • It writes none of the mapped properties to the existing contact, so that contact keeps its owner.
  • An owner picked by Round-Robin for the rejected create does not count as a queue assignment.
If HubSpot rejects the create with any other message, the step fails. This is a safety net. Match Record is still the step that routes known contacts down their own branch.

​
Match options for HubSpot contacts

Match Details lists the contact properties you can filter on, including custom properties, and needs at least 1 condition before the workflow can be published. With Match by association on, the node ignores Match Details and considers only contacts associated with the Source record.

​
When several HubSpot contacts match

An email search usually returns 1 contact. Name and company searches can return several. Prioritize matched records by picks 1. Select Add tiebreaker: Rules run from top to bottom, and only when 2 or more contacts match. A single matching contact is used as it is, so put a hard requirement in Match Details instead. Prefer records where… keeps only the contacts that meet it. When none of the remaining contacts meets it, Default skips the rule, keeps those contacts for the next rules, and adds a warning to the run log. Without any rule, Default takes the first contact HubSpot returns, and that order is not defined. Default does not merge duplicate contacts. The rules only decide which one the workflow uses.

​
When no HubSpot contact matches

The node follows No Match when no contact has the email. The run log then shows No matching records found. It also follows No Match, without searching, when the email is empty for that run. The run log then shows a warning that the match conditions could not be built because upstream data was missing. Create the contact on No Match. If the email can be empty, add a Multi-Branch node before Match Record so a submission without an email takes its own path instead of creating a contact with no email. See Logic and timing nodes.

​
Build a workflow that routes only new HubSpot contacts

This example handles a demo request form. Known contacts keep their owner, and the owner gets a Slack message. New people become contacts owned by the next member of a queue named Inbound Leads.
1

Add the trigger

In Workflows, create a workflow and add the Form Submission trigger. Set Connected Form to your demo request form.
2

Match the contact by email

Add Match Record from the Records section. Set CRM to HubSpot and Record to Contact. Under Match Details, select Edit, choose Email and equals, and pick the email from the form. Select Save changes.
3

Tell the owner about a known contact

On the Match branch, add Send Slack Message. Under Recipients, choose the contact’s Contact owner from the Match Record step. Write the Message, and insert form answers with {{. Leave the contact’s owner unchanged.
4

Pick an owner for a new contact

On the No Match branch, add Round-Robin from the Actions section and set Queue to Inbound Leads.
5

Create the contact

Add Create Record. Set Platform to HubSpot and Record Type to Contact. In Mapped Fields, map Email, First Name, and Last Name from the form, and set Contact owner to Latest assigned user under Round robin.
6

Test and publish

Select Test and run the form trigger once with the email of an existing contact and once with a new email. Check HubSpot after each run. Then select Publish and check that the status next to the deployment switch reads Live. A new workflow goes live when you first publish it. If the status reads Paused, turn the switch on.
A workflow test performs real actions in HubSpot. Use test contacts.
The owner in the Slack step needs a HubSpot Owner ID and a Slack User ID in Settings → Users, so Default can turn the contact owner into a Slack user. Teams that do want to reroute existing contacts can add a Round-Robin node and an Update Record node that sets Contact owner on the Match branch. To link a new contact to its company, continue from Create Record with the steps in HubSpot contact-to-company matching.

​
When 2 runs for the same email overlap

Match Record and Create Record are separate steps with no lock between them. If 2 runs for the same email overlap, for example 2 form fills a second apart, both can find no contact and both try to create one. HubSpot’s rule that a contact’s email is unique is the guard here. The second create is rejected, so HubSpot keeps 1 contact. When the rejection says another record already has that email, Create Record continues with the contact the first run created, or with an empty ID when the rejection names no contact ID, as described in Why Match Record runs before Create Record in HubSpot. The second run still took its own Round-Robin pick and runs the steps after Create Record, such as a Slack message. Its pick is not written to the contact and does not count as an assignment. If HubSpot words the rejection differently, the second run’s Create Record step fails instead. Records matched on other properties, or created without an email, have no such guard. An overlap can then create 2 contacts.

​
Check and troubleshoot HubSpot contact matching

Open the workflow, select Runs at the top, and select a run. Each Match Record step shows its conditions and the record it chose, and each Create Record step shows the properties it wrote. See Run logs. Related: Lead routing software from Default