Eleven Rules for Merging CRM Records at Scale

This is the last section of the dedupe case study, on its own, because it is the part people forward. Every rule was paid for. The platform was HubSpot; the rules transfer to any CRM where merges are irreversible, which is all of them.

1. Put the credential in a workflow secret. Never let it leave the platform. Merge calls should originate from the vendor’s own servers under an app the portal owner created. No external system in the call path.
2. Make the higher-stage record the survivor. Always. A merge adopts the furthest-down-funnel stage and stamps a fresh date entered on a promoted survivor. The higher-stage survivor’s stage never changes; no new stamp is written.
3. Re-fetch both records at run time. Never trust the CSV. Anything that changed between analysis and execution — an owner, a deal, a key — is caught only if you look again.
4. Enforce every safety rule in the code, not in the file. A boundary that lives in which rows are in the spreadsheet is bypassed by a different spreadsheet on a different day.
5. Turn on the action’s rate limit before the first batch above fifty. Without it, records over the platform’s internal throughput continue to the next step with no code result and no error.
6. Let 429 and 5XX throw. A catch block that returns transient errors as output tells the platform the run succeeded, and its built-in retry never fires.
7. After every batch, compare code executions to enrolments. This one comparison is the tripwire for silent partial batches. In the case study it would have caught 204 skipped records that reported no error anywhere.
8. Keep re-enrolment off, and know that it means held records need a deliberate retry. A survivor inherits the secondary’s enrolment history; nothing re-enrols by accident, and nothing retries by accident either.
9. Expect the survivor to inherit the label; clear it inside the code. No downstream workflow action runs for a merged record, so the clean-up cannot be a later step.
10. Quantify the date entered current stage exposure before you run; decide it on the record. If the merged history contains a later entry into a different stage, the field is restamped to merge time. Know how many records that touches, and get that number accepted in writing.
11. Run three rows that cannot merge before you run one that can. A non-numeric target, a self-reference, and a real pair inverted on purpose to fire the orientation guard. Proves the plumbing end to end at zero risk.

Then the gates: one real merge checked field by field; ten pairs across stage combinations and countries; a stratified 250 that mirrors the full mix. The workflow off between every gate. Every batch authorised explicitly. Every irreversible action with a captured before-state.

If the portal you are looking at is one you inherited and you would rather have someone else run these rules first, that is the Inherited Systems Audit — read-only, three weeks, credited against the fix.