How it works
What this system does
This is a coordinated n8n package for reviewing duplicate HubSpot contacts and companies. PostgreSQL stores scan jobs, review decisions, and audit evidence; HubSpot remains the source of CRM records. Import all six workflows separately. The preview shows only workflow 01, not the complete system.
From detection to a reviewed decision
An authenticated scan enters workflow 01 and is persisted before workflow 02 searches for matching records. The detector scores evidence, recommends a primary record, and stores candidates at the supplied score floor of 40. It creates review tasks at scores of 60 or higher. Exact email matches score 100; weaker matches need closer review. A score never authorizes a merge.
Workflow 03 exposes pending reviews and accepts an approval or rejection with an expiring, single-use token. The reviewer selects the primary record. Different owners require an explicit manager override; that override does not bypass other blockers.
Protected execution and recovery
Workflow 04 fetches both records again, checks for changed records and conflicting associations or consent, and saves a pre-merge audit snapshot. It fills only permitted empty fields before the native merge. The supplied configuration has execute_merges set to false. All six workflows import inactive.
Native merge requests have no automatic retry. Ambiguous attempts are reconciled by reading the old IDs; unresolved outcomes require manual review. The system records the returned result ID. Audit snapshots preserve evidence; they are not an unmerge feature. Treat native merges as irreversible.
Workflow 05 is optional manual property setup. Workflow 06 captures failures and monitors queue health.
Validation status
The supplied report describes static structure, syntax, scoring, and guard checks. It explicitly does not verify live HubSpot calls, execution in n8n, or PostgreSQL DDL. Validate this package in your own sandbox before using it with production records.
How to use
Before you start
Use this package when you need controlled duplicate cleanup with an accountable reviewer. You need n8n, a dedicated PostgreSQL database, and HubSpot access to the relevant contacts, companies, and tasks. Confirm the required read/write permissions for your account. Assign an operator and a reviewer before enabling any schedules.
1. Download and prepare
Download the complete ZIP below and extract it. Read README.md and validation-report.txt. Import only the six .n8n.json files into n8n, separately, and keep them inactive. The SQL, property definitions, samples, and report are supporting files.
2. Prepare storage and credentials
Review database-setup.sql and run it in your dedicated PostgreSQL database to create the duplicate_cleanup schema and functions. Configure PostgreSQL credentials in each imported workflow. Configure HubSpot Header Auth with your account token as the Authorization Bearer value. Create separate Header Auth credentials for scan intake, approval access, and external operations access. Keep tokens in n8n credentials and restrict approval access to authorized reviewers.
3. Connect the imported workflows
Replace every REPLACE_* placeholder, including HubSpot owner and portal IDs and the public n8n URL. In workflow 01, set Start Duplicate Detector to your imported workflow 02. Set workflow 06 as the error workflow for workflows 01, 02, and 04. Review configuration nodes and webhook authentication before activation. Inspect hubspot-duplicate-properties.json and run workflow 05 manually only if you want those optional governance properties; do not activate it as a recurring job.
4. Test a scan in your sandbox
Use sample-scan-request.json with sandbox record IDs. Send an authenticated POST to your n8n production webhook URL ending in /webhook/revops-li-005-scan after enabling the intake for testing. For the n8n test listener, use the test URL shown by n8n instead. The body contains event_id, object_type (contacts or companies), and record_id. Generate a new stable UUID for each intended scan. An identical replay is idempotent; reusing the ID with changed data is rejected.
Confirm that the job is persisted, matching evidence is visible, and the recommended primary record is reasonable. Check both a known duplicate and a distinct pair. Do not interpret a high score as permission to merge.
5. Review and approve safely
Using the separate approval credential, GET /webhook/revops-li-005-pending on your n8n host. Review the evidence, recommendation, expiry, and one-time token. Adapt sample-approval-request.json and POST to /webhook/revops-li-005-decision with candidate_id, approval_token, decision APPROVE, selected primary_id, approver_email, manager_override, and a review note. Use REJECT to decline a candidate. Restrict manager_override to an authorized manager decision.
Keep execute_merges: false in workflow 04 while testing detection and approvals. Verify rejection, expired tokens, replayed decisions, changed-record checks, different owners, contact company associations, deal associations, do-not-contact flags, opt-out conflicts, sequence enrollment, and error handling. Do not weaken blockers to make a test pass.
6. Enable execution deliberately
Only after sandbox acceptance and reviewer sign-off, change execute_merges to true in workflow 04 if actual merges are required. Activate the required intake, review, worker, and operations workflows according to the README. Keep workflow 05 manual. Monitor the queue, audit snapshots, and resulting CRM IDs. If a merge outcome is ambiguous, investigate the reconciliation result rather than resending the merge request. A snapshot does not reverse a native HubSpot merge.
Connect this to your other systems
Use the HubSpot lead routing system for new inbound records and this system for reviewed cleanup. Use the GA4 and HubSpot attribution system to connect traffic and conversion data to CRM records. These are separate packages with separate configuration; website links do not wire their workflows together. Before combining them, test how routing and attribution references reconcile the returned CRM ID after a merge.
Read the Revenue Operations Intelligence blueprint for the wider operating model and the Lead Routing blueprint for intake and ownership design.
Proposal follow-up
The HubSpot Ghosted Proposal Follow-Up & Recovery System adds separately configured five-to-seven-day check-ins, high-value approvals, and reply tasks. It imports inactive with SMTP delivery disabled.