CRM Duplicate Cleanup Skill

Find duplicate contacts and companies in a CRM export, pick the record to keep, fill its blanks from the duplicates, and get merge files for HubSpot and Salesforce. It works as a Claude Code plugin (skill crm-duplicate-cleanup) or a command-line tool. Python 3.9+, no dependencies. It's read-only: it never connects to your CRM.

python3 -m crmdedupe contacts hubspot-contacts.csv --out dedupe/
python3 -m crmdedupe companies salesforce-accounts.csv --out dedupe/
./demo.sh          # bundled HubSpot contacts example
./run_tests.sh     # 13 tests, including a 20,000-row run

Accents, punctuation, &, phone formats, extensions and +1 are normalized. Ten-digit numbers without + are treated as US/Canada. Use --country-code 44 or --country-code '' to change that.

• clusters.csv: every duplicate group with master or duplicate role, the reason, and all original columns.
• review_pairs.csv: possible duplicates that are never merged automatically.
• master_updates.csv: master fields that are blank but filled on a duplicate. Apply these first: Salesforce keeps the master's values, blanks included, when merging.
• deduped.csv: one row per real person or company, with blanks filled and a merged_rows column.
• salesforce_merge.csv: master ID plus up to 2 merge IDs per row. Salesforce merges at most 3 records at once, so larger groups are split into successive merges.
• hubspot_merge_requests.jsonl: one POST /crm/v3/objects/contacts/merge (or companies/merge) body per duplicate, as {"primaryObjectId", "objectIdToMerge"}.
• summary.json

Master rule (--master): most-complete (default: most filled fields, then oldest create date), oldest, or newest (latest modified or activity date).

Column detection covers HubSpot and Salesforce export headers (Record ID, Contact ID, Account ID, Email, First/Last Name, Company Name or Account Name, Phone Number, Website or Company Domain Name, City, Create/Created Date, Last Modified/Activity Date). Override any column with --email-col, --company-col, --id-col, --phone-col and so on.

• It plans merges; it doesn't perform them. Merges can't be cleanly undone in HubSpot or Salesforce, so test 1 group first.
• Matching is rule-based, not ML. Unusual name orders, or people who share both a phone and a name, may need review.
• Very common blocking keys (for example thousands of rows with the same last-name prefix) are skipped and reported. Exact email and phone matches are still found through their own blocks, unless that email or phone is itself shared by hundreds of rows.