HubSpot Search and Replace: Step-by-Step Tutorial

This tutorial walks through a complete search-and-replace operation in HubSpot, from connecting your portal to verifying the results. We will use a real-world example: standardizing a company name across contact records after a rebrand.

The scenario: Your company has rebranded from "Acme Solutions" to "Acme Technologies." The old name appears in the Company Name property on hundreds of contact records, in deal names, and in notes. You need to update all of them.

Here's a preview of what the end result looks like:

Before you start

You will need:

• A HubSpot account with admin or super admin permissions (required for the OAuth connection to have sufficient access)
• A SearchReplace account (the free plan works for up to 100 records per year)
• About 10 minutes

A quick note on permissions: SearchReplace connects to HubSpot via OAuth 2.0, which means it requests specific scopes (read/write access to CRM objects and CMS content). The HubSpot user who authorizes the connection needs sufficient permissions to grant those scopes. In most portals, this means admin-level access.

Step 1: Create your SearchReplace account

Go to the signup page and create an account with your email address. No credit card is required for the Free plan. You will receive a confirmation email — click the link to verify your account.

Once logged in, you will see the dashboard. It will be empty since you have not connected a HubSpot portal yet.

Step 2: Connect your HubSpot portal

Click Connect Portal on the dashboard (or navigate to Portals in the sidebar). This starts the HubSpot OAuth flow:

1. You are redirected to HubSpot's authorization page
2. HubSpot shows you which portal you are connecting and what permissions SearchReplace is requesting
3. Click Grant access
4. You are redirected back to SearchReplace with the portal connected

The connection is now live. SearchReplace can read and write to your HubSpot CRM and CMS objects. You can revoke this access at any time from HubSpot > Settings > Integrations > Connected Apps.

Your portal appears on the dashboard with its name and HubSpot portal ID. Custom multi-portal packages are available through Enterprise; each connected portal appears as a separate card.

Step 3: Start a new search-and-replace operation

Click Search & Replace in the sidebar, or click the action button on your portal card. This opens the search configuration form.

Select the object type

The first dropdown lets you choose the object type. Options include:

• Contacts
• Companies
• Deals
• Tickets
• Blog Posts
• Landing Pages
• Any custom objects defined in your portal

For our example, select Contacts.

Select the property

The second dropdown populates with all text-based properties for the selected object type. For contacts, this includes properties like First Name, Last Name, Email, Phone Number, Job Title, Company Name, and any custom text properties you have created.

Select Company (this is HubSpot's built-in Company Name property on contact records).

Choose the search mode

Three options:

• Exact match — The entire property value must equal your search string. Use this when you want to find records where the company name is exactly "Acme Solutions" and nothing else.
• Substring — Finds your search string anywhere within the property value. Use this when "Acme Solutions" might appear as part of a longer string, like "Acme Solutions Inc." or "Acme Solutions - West Coast."
• Regex — Regular expression pattern matching. Available on Professional plans and above. Use this for complex patterns, case-insensitive matching, or when you need capture groups in the replacement.

For our example, select Substring. This ensures we catch "Acme Solutions" whether it appears alone or as part of a longer company name.

Enter the search string

In the Find field, type: Acme Solutions

Enter the replacement string

In the Replace with field, type: Acme Technologies

Step 4: Preview the changes

Click Preview. SearchReplace queries your HubSpot portal for all contact records where the Company property contains "Acme Solutions."

The preview screen shows a table with:

• Record — The contact name and HubSpot record ID, linked to the record in HubSpot
• Current value — The existing Company property value
• New value — What the value will become after replacement

For example:

Notice how the substring replacement correctly handles each variation. "Acme Solutions" is replaced with "Acme Technologies" within whatever larger string it appears in.

Reviewing the preview

Take a moment to scan the preview list. Look for:

• Unexpected matches — Does any record match that should not be changed? If a different company happened to have "Acme Solutions" in their name and should not be updated, you can exclude individual records from the operation by unchecking them.
• Truncation or formatting issues — Does the replacement create awkward text? For example, if a company name was "Acme Solutions/Acme Services" and you only want to change "Acme Solutions," verify the result looks right.
• Record count — Is the number of matches what you expected? If you expected 200 matches and got 50, your search might be too narrow. If you got 2,000, it might be too broad.

Adjusting the search

If the preview does not look right, click Back to return to the search form. Adjust your search string, change the search mode, or refine the property selection. Preview again until the results match your intent.

Step 5: Execute the replacement

Once the preview looks correct, click Replace. SearchReplace begins processing the updates.

A progress indicator shows:

• Total records to update
• Records completed
• Current status (processing, complete, or error)

SearchReplace processes updates in batches, automatically managing HubSpot's API rate limits. A 200-record operation typically completes in under a minute. Larger operations (thousands of records) may take several minutes.

You do not need to keep the browser tab open. The operation continues server-side. You can check progress from the Audit page at any time.

Step 6: Verify the results

After the operation completes, you will see a summary:

• Total records updated
• Operation ID (for reference in the audit log)
• Timestamp
• Rollback status (available)

Go to Audit in the sidebar to see the complete operation record. The audit entry includes:

• Who ran the operation
• When it ran
• Object type and property
• Search pattern and replacement value
• Total records affected
• Status (completed, rolled back, etc.)

You can also spot-check in HubSpot itself. Navigate to one of the updated contacts and verify the Company property shows the new value.

Step 7: Roll back (if needed)

If you discover a problem after the replacement — maybe you replaced a value you did not intend to, or the replacement created an unexpected result — you can roll back the entire operation.

From the Audit page, find the operation and click Rollback. SearchReplace restores every affected record to its original value. The rollback itself is logged as a separate audit entry.

The rollback window depends on your plan:

Rollback restores the exact original values that were captured before the replacement. If a record was modified by another process between the replacement and the rollback (a workflow updated the value, or someone manually edited it), the rollback will overwrite those intermediate changes with the pre-operation snapshot. Keep this in mind when deciding whether to roll back.

Going further: Regex replacements

For the Professional plan and above, regex search mode opens up more powerful operations.

Example: Reformatting phone numbers

Search pattern: \((\d{3})\)\s*(\d{3})-(\d{4})

Replacement: +1-$1-$2-$3

This converts phone numbers from (555) 123-4567 format to +1-555-123-4567. The parenthesized groups in the search pattern are captured and referenced as $1, $2, and $3 in the replacement.

Example: Case-insensitive matching

To match "Acme Solutions" regardless of capitalization (e.g., "acme solutions," "ACME SOLUTIONS," or any other variant), enable the Case-insensitive toggle in the search options UI, then enter your search pattern normally:

Search pattern: acme solutions

The toggle applies case-insensitive matching to the entire search, so you do not need to use inline regex flags.

Example: Removing prefixes

Search pattern: ^(Mr\.|Mrs\.|Ms\.|Dr\.)\s+

Replacement: (empty string)

This strips honorific prefixes from the beginning of a name field, which is useful after an import that included titles in the name field.

Tips for smooth operations

Start with the most specific search. It is better to run two targeted operations than one broad operation that catches unintended records. You can always run another operation for the cases you missed.

Use the preview as your safety net. Never skip the preview step. Even simple operations can produce unexpected results if the data contains variations you did not anticipate.

Check your plan limits. Each operation counts successfully updated records against your allowance. A 100-record Free allowance cannot run a 400-record operation; preview the full change, then use the 500-record Cleanup Pass or Professional to apply it. The dashboard shows your current usage.

Coordinate with your team. If multiple people have access to SearchReplace or are making manual changes in HubSpot, communicate before running large operations. Overlapping edits can create confusion.

That is the complete workflow. Connect, search, preview, replace, and roll back if needed. The same steps apply whether you are updating 10 contacts or 10,000 deal records.