Safe Merge Documentation

Getting Started

Safe Merge installs in under 2 minutes via HubSpot's standard OAuth flow. No credit card required for the free tier.

Prerequisites

• An active HubSpot account: Free CRM or any paid Hub
• Super Admin access or sufficient permissions to install integrations and manage CRM properties
• Authority to connect third-party apps: confirm your IT policy allows it

Quick Install

Setup Guide: Install to First Snapshot

This is a comprehensive step-by-step walkthrough from installing Safe Merge to your first automated snapshot and duplicate detection run.

Step 1: Install Safe Merge

Visit safemerge.app and click "Install Free." HubSpot will ask you to authorize the required OAuth scopes. Select the portal you want to protect and click "Connect app."

Step 2: Log in to the Account Portal

After installation, go to safemerge.app/account. Click "Log in with HubSpot" to authenticate. This is your central dashboard for all Safe Merge settings, duplicate review, and billing.

Step 3: Configure Snapshot Protection

On the Account Portal, find the Snapshot Protection card. Here you will:

1. Choose object types: Select which CRM objects to protect: contacts, companies, deals, or any combination.
2. Limit to specific segments (optional): Click "Limit to specific segments" to pick specific HubSpot lists for each object type. Only records in those lists will be snapshotted. This helps you stay under your plan's record limit by focusing protection on your most important data. Leave empty to snapshot all records of that type.
3. Choose your timezone: Select your timezone from the dropdown (e.g., "America/New_York").
4. Choose your snapshot time: Pick the time you want your nightly snapshot to run (e.g., 2:00 AM). We recommend choosing a time when your team is not actively working in HubSpot.

Step 4: Enable Snapshot Protection

Click "Enable Snapshot Protection" to opt in. Snapshot protection is not automatic on install. You must explicitly enable it. Once enabled, Safe Merge will run your first snapshot at the next occurrence of your chosen time.

Configure snapshot schedule, enrolled objects, and segment filters from the web portal

Step 5: First Snapshot Runs

At your chosen snapshot time, Safe Merge will:

1. Snapshot all records of your selected object types
2. Automatically run duplicate detection on the snapshotted records
3. Display any detected duplicates in your Account Portal dedup dashboard

Step 6: Review Duplicates

After your first snapshot completes, visit the dedup dashboard in your Account Portal. You will see any detected duplicate pairs with match scores and reasoning. From there you can Safe Merge (with snapshot protection), dismiss false positives, or view the match reasoning.

Step 7: Ongoing Protection

From this point forward, Safe Merge runs automatically at your chosen time based on your plan's scan frequency. Each snapshot also triggers a fresh duplicate detection run, so new duplicates are surfaced continuously.

How Snapshots Work

Snapshots are the foundation of Safe Merge. They capture a complete, compressed JSON snapshot of every record's properties and associations, so any merge can be fully reversed.

Nightly Cron at Your Chosen Time

Safe Merge runs an automated snapshot job at the time you configure in the Snapshot Protection settings. You choose both your timezone and your preferred snapshot time. The job checks each portal's scan schedule and runs snapshots for portals that are due:

Automatic Duplicate Detection

During each snapshot run, duplicate detection runs automatically on the snapshotted records. This means you do not need to manually trigger scans. Duplicates are surfaced in the dedup dashboard after each snapshot cycle.

Incremental Snapshots

After the initial full snapshot, subsequent runs are incremental: only records modified since the last snapshot are re-captured. This keeps processing fast and efficient, even for large portals.

Where Snapshots Are Stored

• PostgreSQL database: The full compressed snapshot is stored server-side in our encrypted PostgreSQL database on Render (Oregon, US)
• HubSpot property indicator: A lightweight custom property (safe_merge_snapshot) is written to the record in HubSpot, marking it as protected and storing the snapshot timestamp. This allows the CRM card to instantly display protection status without an API call.

Snapshot Retention

Snapshots are retained based on your plan tier. Older snapshots are automatically pruned:

Duplicate Detection

Safe Merge uses a 3-stage pipeline to find duplicates across your contacts, companies, and deals. Each stage adds increasing sophistication, filtering candidates down to high-confidence pairs. Duplicate detection runs automatically during each snapshot cycle.

Stage 1: Exact Matching

The first pass applies fast, exact-match rules to identify obvious duplicates:

• Exact email match: Two contacts with the same email address (case-insensitive)
• Exact phone match: Two contacts with the same phone number (normalized)
• Domain match: Two companies with the same website domain (normalized, stripping www/subdomains)

These pairs are flagged with high confidence (0.95+) and do not require further evaluation.

Stage 2: Fuzzy Matching

For records that do not match exactly, Safe Merge applies probabilistic record linkage based on the Fellegi-Sunter model:

• Jaro-Winkler distance for names: Catches typos, abbreviations, and name variations (e.g., "Jon Smith" vs. "Jonathan Smith")
• Phone digit normalization: Strips formatting and compares raw digit sequences (e.g., "(555) 123-4567" vs. "5551234567")
• TF-IDF company name similarity: Accounts for common words like "Inc", "LLC", "Solutions" that reduce match significance, while weighting distinctive terms higher

Pairs scoring above 0.70 advance to the next stage. Pairs scoring 0.95+ from Stage 2 are treated as confirmed duplicates.

Stage 3: Advanced Matching with Web Verification (Growth+ Plans)

For ambiguous pairs in the 0.70 to 0.95 score range, Safe Merge sends the pair to Anthropic's advanced pattern matching service for contextual evaluation:

• The service analyzes property patterns, naming conventions, and contextual signals
• Returns a match/no-match verdict with a confidence score and reasoning
• Handles edge cases like maiden names, company acquisitions, and name transliterations

For Growth, Pro, and Enterprise plans, this stage also adds web search verification for company duplicates:

• Company domain verification: Confirms two company names resolve to the same domain
• LinkedIn cross-reference: Checks LinkedIn company pages for matching data
• Acquisition detection: Identifies companies that merged or acquired each other (different names, same entity)

The dedup dashboard shows all detected pairs with match scores, verdicts, and one-click merge or dismiss actions

Dedup Dashboard

The dedup dashboard is your central hub for reviewing and acting on detected duplicates. Access it from your Account Portal.

Reviewing Duplicates

After each snapshot and duplicate detection run, detected pairs appear in the dedup dashboard. For each pair you can see:

• Match score: A confidence percentage indicating how likely the pair is a true duplicate
• Match reasoning: Explanation of why the records were flagged (e.g., "exact email match", "name similarity 0.92 + same company domain")
• Record details: Side-by-side comparison of key fields from both records

Actions

For each detected duplicate pair, you have three options:

1. Safe Merge: Merge the records with full snapshot protection. A pre-merge snapshot is captured automatically, so you can undo the merge with one click if needed.
2. Dismiss: Mark the pair as not a duplicate. Dismissed pairs will not appear again in future scans.
3. View Reasoning: See the detailed match analysis, including which fields matched and the confidence breakdown.

Review each pair with side-by-side property comparison and per-field match confidence scores

Unmerging from the Dashboard

If you merged a pair from the dedup dashboard and need to reverse it, merged pairs appear in your operations history. Click "Unmerge" to restore both records to their pre-merge state with 100% fidelity from the snapshot.

After unmerge, review the surviving and recreated records with 100% snapshot fidelity confirmation

Safe Merge with Undo

When Safe Merge identifies duplicates, you can merge them directly from the dashboard or CRM card with full undo capability.

How It Works

1. Pre-merge snapshot: Before any merge, Safe Merge captures a complete snapshot of both records (all properties + all associations)
2. Merge via HubSpot API: The merge is executed through HubSpot's native merge API, ensuring full compatibility with HubSpot's merge behavior
3. Undo available immediately: After the merge completes, a one-click "Undo" button appears in the CRM card and on your account dashboard

One-Click Undo

If a merge needs to be reversed:

1. Navigate to the merged record in HubSpot, or find the merge in your account dashboard
2. Click "Undo Merge"
3. Confirm in the dialog
4. Processing takes 5 to 30 seconds
5. Links to the restored records appear when complete

What Gets Restored

• All writable properties from the pre-merge snapshot with 100% fidelity
• All associations: contacts, companies, deals, notes, tasks, calls, emails, meetings
• Read-only properties stored in a safe_merge_readonly_values mirror property for reference
• Surviving record cleanup: absorbed associations are removed and the surviving record is restored to its pre-merge state

Safe Merge supports undo for contacts, companies, and deals.

Chain Merges

If a record was merged multiple times, Safe Merge handles it automatically with timestamp-aware snapshot matching. All abolished records are shown in the sidebar card and can be individually restored.

Account Dashboard

The web portal at safemerge.app/account is your central hub for managing Safe Merge.

Dashboard Sections

• Snapshot Protection: Configure which object types to protect, your timezone, and your preferred snapshot time. Optionally limit snapshots to specific HubSpot segments (lists) per object type. Enable or disable snapshot protection.
• Snapshot Status: See when your last snapshot ran, how many records are protected, and when the next snapshot is scheduled
• Dedup Dashboard: View detected duplicate pairs, filter by object type (contacts/companies/deals), review match scores and reasoning, and approve or dismiss pairs
• Operations History: Complete log of all merges, unmerges, and snapshot operations with timestamps, status, and details
• Billing Management: Current plan, record usage, upgrade/downgrade options, and a link to the Stripe billing portal for invoices and payment methods
• Emergency Unmerge Credits: Current credit balance and purchase options (paid Safe Merge plans include a monthly EU allowance)

Bulk operations let you scan and unmerge multiple records from a HubSpot list or CSV upload

Cancellation

• Cancel anytime from the Stripe billing portal (linked from your Account page)
• Takes effect at the end of the current billing period
• Unmerge is disabled immediately; snapshots continue for a 14-day grace period
• After the grace period, your portal reverts to Free tier limits

HubSpot CRM Cards

Safe Merge installs two CRM cards on every contact, company, and deal record in your HubSpot portal.

SafeMergeCard (Sidebar Card)

The sidebar card appears in the right panel of every record and shows:

The card also displays any detected duplicate pairs for the current record, with match scores and a direct link to review/merge them.

The sidebar card and tab card appear on every contact, company, and deal record in HubSpot

SafeMergeTabCard (Unmerge Workflow)

The tab card provides the full unmerge workflow when a merge is detected:

• Snapshot-based unmerge: One-click restore from the pre-merge snapshot
• Emergency Unmerge: For records merged before Safe Merge was installed, launches the reconstruction workflow (scan, review, execute)
• Operation status: Shows progress for in-flight unmerge operations

When a merge is detected, the tab card shows full details and lets you preview snapshots or execute an unmerge

Pricing & Plans

Annual billing saves up to 29%. All prices are in US dollars and exclude applicable taxes.

Emergency Unmerge Integration

Emergency Unmerge is a separate product by Third Space that reconstructs records merged before Safe Merge was installed, when no pre-merge snapshot exists.

How It Works

1. Deep scan: Reads all properties, associations, and engagement history on the merged record (30 to 120 seconds)
2. Reconstruction: Anthropic's advanced pattern matching service analyzes property history, timestamps, association patterns, and email domain forensics to reconstruct the probable pre-merge state
3. Human review: You review the proposed reconstruction side-by-side, with confidence scores for every property. Edit any field before executing.
4. Execution: Only after your explicit approval are new records created in HubSpot

Cross-Product Benefit

Any paid Safe Merge subscription includes a monthly allowance of Emergency Unmerge operations:

• Starter: 10 EU operations/month included
• Growth: 25 EU operations/month included
• Pro: 50 EU operations/month included
• Enterprise: Unlimited EU operations included

Operations within the monthly allowance require no credits. Operations beyond the allowance use standard credit rates ($0.05/credit for Starter, $0.04/credit for Growth and above). Allowances reset on the first of each month and do not roll over.

Free plan users can use Emergency Unmerge by purchasing credits. See the Emergency Unmerge documentation for complete details on credits and pricing.

Emergency Unmerge Credits (Free Plan)

Credit Cost by Record Complexity

• The exact cost is shown before confirmation. Credits are only deducted on successful execution.
• All purchases are final and non-refundable
• Non-transferable between portals
• Expire 12 months after purchase

OAuth Scopes Explained

Required Scopes

Optional Scopes

Optional scopes are only used during Emergency Unmerge to provide richer data for reconstruction analysis. You can decline them and still use all core features.

Shared Data Flow

Data flows bi-directionally for contacts, companies, and deals:

• HubSpot to Safe Merge: Property values, associations, and merge history are read for snapshot creation, merge detection, and duplicate scanning
• Safe Merge to HubSpot: New records are created during unmerge; snapshot indicator properties are written; associations are created and removed during unmerge operations; merges are executed via HubSpot's merge API

Data Handling & Security

Where Your Data Lives

Security Measures

• TLS 1.2+ encryption for all API traffic
• OAuth tokens encrypted at rest (Fernet / AES-128-CBC + HMAC-SHA256)
• Database access restricted to application service only
• HTTPS enforced with HSTS headers
• Sentry error monitoring with PII sending disabled
• Render.com SOC 2 Type II certified infrastructure
• Your CRM data is never used to train models (per Anthropic Commercial Terms)

For complete details, see our Privacy Policy, Data Processing Agreement, and Security pages.

Troubleshooting

"No Snapshot Yet" on the Sidebar Card

This means the record has not been captured in a snapshot cycle yet. Snapshots run on a schedule based on your plan tier (monthly for Free, weekly for Starter/Growth, daily for Pro/Enterprise). The record will be picked up in the next scheduled cycle automatically. If you just installed Safe Merge, make sure you have enabled Snapshot Protection in the Account Portal and the first snapshot will run at your chosen time.

"Token Expired" or Authorization Errors

If Safe Merge loses access to your HubSpot portal, the CRM card may show an authorization error. To resolve:

1. Go to HubSpot Settings → Integrations → Connected Apps
2. Find Safe Merge and disconnect it
3. Reinstall from safemerge.app
4. Your account data (plan, history, credits) will be automatically reconnected

"Scan Running": Duplicate Scan Already in Progress

Safe Merge processes one duplicate scan at a time per object type. If a scan is already running for contacts, you cannot start another contact scan until it completes. Scans typically complete within a few minutes for most portals. Large portals (100k+ records) may take longer.

Unmerge Button Is Disabled

Possible causes:

• Monthly limit reached: Free plan allows 3 unmerges/month. Upgrade or wait until the next billing cycle.
• Payment failed: Unmerge is disabled immediately when payment fails. Update payment at safemerge.app/account.
• No merge detected: The record has no hs_merged_object_ids. It may not have been merged, or HubSpot may not have recorded the merge.

Unmerge Completed but Some Associations Are Missing

Possible reasons:

• Association was created after the last snapshot: Safe Merge restores from the snapshot. Associations added between the snapshot and the merge are not captured.
• HubSpot rate limits: Extremely complex records (hundreds of associations) may hit HubSpot API rate limits. Wait a few minutes and check again.

Properties Show as "Read-Only Mirror"

Certain HubSpot properties (e.g., createdate, hs_analytics_source) are system-managed and cannot be written by any integration. Safe Merge stores these values in safe_merge_readonly_values so you have a reference.

Sidebar Card Shows an Error

Try refreshing the page. If the issue persists, it may be a temporary API issue. Contact joshua@thirdspaced.com with your portal ID and the record URL.

Frequently Asked Questions

Does Safe Merge work with HubSpot Free CRM?

Yes. Safe Merge works with all HubSpot tiers, including the free CRM.

Do snapshots start automatically when I install?

No. After installing, you need to go to safemerge.app/account, configure your object types, timezone, and snapshot time, then click "Enable Snapshot Protection." Nothing runs until you opt in.

Can I unmerge records that were merged before I installed Safe Merge?

Yes, that is what Emergency Unmerge is for. It uses advanced reconstruction to determine the probable pre-merge state, even without a snapshot. Paid Safe Merge subscribers get Emergency Unmerge for free.

Is my data safe?

Snapshots are stored in our encrypted PostgreSQL database, with a lightweight indicator property written to your HubSpot records. OAuth tokens are encrypted at rest. Our infrastructure is SOC 2 Type II certified. Your data is never used to train models. See our Privacy Policy and Security page.

What happens if I uninstall Safe Merge?

Your CRM data is unaffected. Custom properties remain on your records (you can delete them manually in HubSpot Settings → Properties). Our stored data (tokens, snapshots, logs) is deleted within 30 days.

Does Safe Merge work with custom objects?

Currently, Safe Merge supports contacts, companies, and deals. Custom object support is on our roadmap.

How is this different from a CRM backup tool?

Backup tools export your entire CRM to an external location. Safe Merge is purpose-built for merge protection and duplicate management: it captures pre-merge state, detects duplicates with a 3-stage pipeline, safely merges them with full undo capability, and can surgically reverse merges with one click. It is not a general backup. It is a complete merge safety net.

How does duplicate detection differ from HubSpot's built-in tool?

HubSpot's built-in duplicate tool uses basic matching. Safe Merge adds Fellegi-Sunter probabilistic scoring, advanced matching for ambiguous pairs, and web search verification for companies. Most importantly, Safe Merge lets you merge duplicates with a full undo guarantee, something HubSpot's native merge does not offer.

Can I get a refund?

No. All subscription payments and credit purchases are final and non-refundable. If you experience a genuine service issue, contact support and we can provide service credits or complimentary time as appropriate. See Terms of Service, Section 3.6.

Support

When contacting support, include:

• Your HubSpot Portal ID
• The URL of the affected record (if applicable)
• A description of the issue and any error messages

Third Space, LLC
Email: joshua@thirdspaced.com
Website: https://safemerge.app