HubSpot Custom Workflow Guide: How to Automatically "Search" for and "Associate" Contacts

Purpose of the Action

The primary purpose of this action is to search your HubSpot database for a different contact (Contact B) based on information from the contact currently enrolled in the workflow (Contact A).

The action's only output is the Record ID (Contact ID) of the contact it finds. The ultimate goal is to use this ID in a subsequent step to automatically associate Contact A and Contact B.

Common Use Cases

This action is extremely powerful for automatically building relationships between your contacts.

• Referral ProgramsWhen a new contact (A) signs up with a "Referrer Code," this action can search for the existing contact (B) who owns that code. If found, it can then associate A and B.
• Family or Household LinkingWhen a new event attendee (A) registers, this action can search for another contact (B) with the same "Last Name" AND "Postal Code" and then automatically associate them.
• B2B Contact-to-Account LinkingWhen a new contact (A) is created, this action can search for an existing contact (B) with the same "Company Domain" and associate them.

Step-by-Step Guide from the Video Demo

The video demonstrates the setup and execution of the search action itself.

Step 1: Add the Action (0:04 - 0:09)In the workflow editor, click the "+" icon to add an action. The left sidebar opens, showing available actions. The video selects the app "Custom Workflow Business V2."

Step 2: Select the "Contact Search Action" (0:10 - 0:12)From the app's list of available actions, click on "Contact Search Action" to add it to the workflow.

Step 3: Configure Search Criteria (0:13 - 0:43)In the action's setup panel on the left, you define who you are looking for.

• First Condition:Set the Condition - Property Name (e.g., First Name), the Condition - Search Operator (e.g., Equal to), and the Condition - Value (e.g., "Brian"). This value can be a static value, as shown, or a personalization token from the enrolled contact.
• Second Condition (Optional):This action allows for a second, combined search condition (the video shows Domain as an option).
• Condition Logic:You can use the Operator between Conditions to set the logic to "AND (both must be true)" or "OR (either can be true)."
• Exclusion:The Contact ID field can be used to exclude a specific contact from the search results (for example, using the enrolled contact's own ID token to avoid finding itself).

Step 4: Save Configuration (0:44 - 0:46)Click the "Save" button. The workflow card updates to show a summary of your criteria (e.g., Search contacts where First Name Equal to Brian).

Step 5: Run Workflow & Check History (0:47 - 0:56)The workflow is turned on and run (using a manual trigger in the demo).After it runs, check the "History" tab. You can see the "Contact Search Action" has "Action succeeded."By clicking to see the log details (right panel), you can inspect the "OUTPUTS" section. It clearly shows the search_results with the Record ID it found (in the video, "501").

Step 6: Verify the Result (0:57 - 1:00)(As a supplement to the demo) You can then go to your HubSpot contact list and confirm that the contact with Record ID "501" is, in fact, "Brian Halligan," confirming the search was successful.

[IMPORTANT] How to Use the Record ID for Association

This action only finds the Record ID. To achieve your goal of associating the contacts, you must add these follow-up steps.

1. Add an If/then BranchImmediately after the "Contact Search Action," add a standard HubSpot "If/then branch" action.
2. Set Branch CriteriaSet the branch condition to check if the output from the "Contact Search Action" (search_results) "is known". This creates a "Yes" path (if a contact was found) and a "No" path (if no contact was found).
3. Add the Association ActionIn the "Yes" (found) branch, click the "+" icon and select the other action provided by this same 3rd-party app. It will likely be named "Associate Contact by ID" or "Associate Object."
4. Configure the AssociationIn this new association action's settings, you will specify two things:
   • From ID (Original Contact): Set this to the contact enrolled in the workflow. Use the [Contact Record ID] token.
   • To ID (Contact to Associate): Set this to the ID you just found. Use the [search_results] token from the search action.

By completing these steps, you create a full automation: Contact A enrolls, the workflow searches for Contact B, and if B is found, the system automatically associates them. As we discussed, this action will create a standard association and does not support adding an association label (e.g., "Family" or "Referrer").

‍