---
name: crm-identity-dedupe
description: Build a CRM deduplication pass that resolves records to an external identity rather than fuzzy-matching names, merges only above a confidence threshold, and runs a dry run first. Use when the user has duplicate CRM records, split lead scores, or wants identity resolution rather than name matching.
---

# Deduplication and identity resolution

> Generated from https://www.reversecontact.com/integrations-hub/workflows/crm-deduplication
> Every tier requirement and limit below was read from the vendor's own documentation on 2026-09-18.
> Vendors change these without notice. Re-check anything load-bearing before you rely on it.

**Tools in this workflow:** HubSpot, Reverse Contact, n8n.
**Build effort:** Days.

## What you are building

Cluster the records that might be the same person, resolve each to a canonical identity, and merge only where two records resolve to the same identity above your confidence threshold. Everything else goes to a review queue. A dry run comes first, always.

## Ask this before writing anything

Is the same person at two different companies over time a duplicate, or a history? This is a policy question and it must be answered before any code. Usually they are the same identity and two legitimate records: one carries the history at the old company, one is the current relationship. Merging them destroys the history. Linking them is almost always right. Get the answer from whoever owns the accounts.

## Prerequisites

| What | Where to get it | Notes |
|---|---|---|
| CRM read and merge permission | A private app, plus the permission to merge | Merging is close to irreversible: confirm the user understands that |
| Reverse Contact API key | Workspace > API Keys | One call per candidate record, not per CRM record |
| A place to run a long job with a dry-run mode | n8n is the right home | You need an audit trail and a review queue, not a one-off script |
| A human who knows the accounts | The user's team | Budget an afternoon of their time. This is a real prerequisite, not a formality |

## The tools, and how to call them

### Reverse Contact

- **Base:** `https://api.reversecontact.com/v2`
- **Auth:** `Authorization: Bearer rc_your_api_key`. Keys are created in Workspace > API Keys.

| Call | Request | What it does |
|---|---|---|
| `POST /v2/enrich/persons` | `{ "email": "j.okafor@northwind.io" }` | Resolve a person from an email, a name plus company, or a profile URL. Cached resolution, returns in the response. |
| `POST /v2/enrich/companies` | `{ "domain": "northwind.io" }` | Resolve a company from a domain or a name. |
| `POST /v2/fetch/persons` | `{ "linkedInUrl": "..." }` | Standard profile lookup from the database. |
| `POST /v2/fetch/persons/live` | `{ "linkedInUrl": "..." }` | Live on-demand resolution. ASYNCHRONOUS: returns a webhookId to poll, not a record. |
| `POST /v2/search/people` | `{ "filters": { "currentCompanyDomain": "northwind.io" } }` | Filtered people search. 1 credit a profile delivered, and /v2/search/people/count is free. It replaced /v2/search/persons, which returns 410 Gone since 13 October 2026. |
| `POST /v2/search/organizations` | `{ "filters": { "companyDomain": "northwind.io" } }` | Filtered company search. A domain can also go straight to a company through POST /v2/enrich/companies, or through the enrich_company MCP tool since November 2026. |
| `POST /v2/contact/email` | `{ "linkedInUrl": "..." }` | Find an email. ASYNCHRONOUS: returns a taskId to poll. 3 credits for a professional address, 5 for a personal one, 8 for both, refunded when neither is found. |
| `GET /v2/webhooks/:webhookId` | - | Poll an async job until status is "succeeded". Polling is free and does not count against the rate limit. |

Response shape:

```json
{
  "success": true,
  "data": {
    "person": {
      "fullName": "Jane Okafor",
      "headline": "VP Sales at Northwind",
      "location": "London, United Kingdom",
      "linkedInUrl": "https://linkedin.com/in/...",
      "currentPosition": { "title": "VP Sales", "companyName": "Northwind", "startDate": "2023-04" },
      "emails": [], "experience": [], "education": [], "skills": []
    },
    "company": { "name": "Northwind", "domain": "northwind.io",
                 "industry": "Software Development", "employeeCount": 220 }
  },
  "error": null,
  "metadata": { "requestId": "req_...", "executionTimeMs": 480, "updatedAt": "2026-09-01T..." },
  "quotas": { "creditsConsumed": 1, "workspace": { "credits": { "total": 10000, "used": 4521, "left": 5479 } } }
}
```

**Rules that will cost you time if you skip them:**

- A miss returns **null**, not a best guess. Every response carries a confidence score, and you can raise the precision threshold on the request. Branch on it: do not treat a low-confidence answer as a match.
- Use the cached endpoints anywhere that must answer inside one HTTP request. The `/live` endpoints return a task and need polling.
- `quotas.workspace.credits.left` is on every response. Log it, or you will find out about the balance from a 402.
- Credit costs per call are published and a dollar rate per lookup is not: 2 credits for a reverse lookup from an email, 1 for a cached profile lookup, 2 for a live refresh, 3 for a business email and 20 for a direct phone number, with the last two charged only when one is found. Checks and the search count endpoint are free. Credit packs expire after 3 months. Do not hard-code a dollar cost assumption.

**MCP server:** `https://api.reversecontact.com/mcp`

- Auth: OAuth 2.1 where the client supports it, otherwise `Authorization: Bearer rc_your_api_key`.
- Tools: `enrich_person`, `enrich_person_live`, `enrich_company`, `enrich_company_live`, `search_persons`, `search_companies`, `check_usage`, `check_task`
- Streamable HTTP, JSON-RPC 2.0. The `_live` tools return a task id that `check_task` polls.

Docs: https://docs.reversecontact.com/getting-started

### HubSpot

- **Base:** `https://api.hubapi.com`
- **Auth:** `Authorization: Bearer <private-app-token>` for a private app, or OAuth for a marketplace app. Full CRM API access is on every tier including Free.

| Call | Request | What it does |
|---|---|---|
| `PATCH /crm/v3/objects/contacts/{contactId}` | `{ "properties": { "rc_title": "VP Sales" } }` | Update a contact. Send only the properties you own. |
| `POST /crm/v3/objects/contacts/search` | `{ "filterGroups": [...], "properties": [...] }` | Find records by property. Use this to pull the slice that is missing a field. |
| `POST /crm/v3/objects/contacts/batch/update` | `{ "inputs": [ { "id": "...", "properties": {...} } ] }` | Batch of up to 100. Prefer this over per-record PATCH at volume: it is one request against the rate limit. |

**Rules that will cost you time if you skip them:**

- **Rate limits.** A private app gets 190 requests per 10 seconds on Professional and Enterprise, 100 on Free and Starter. Daily caps are 250,000 / 625,000 / 1,000,000 calls **per account, shared across every app**. A public OAuth marketplace app is capped at 110 per 10 seconds per installing account.
- **Calling an external API from a workflow needs Data Hub Professional or Enterprise.** Both the webhook action and the custom code action live in that hub, not in Sales Hub. Check this before designing an in-HubSpot build.
- **Custom code actions get 20 seconds and 128 MB.** Combined length of all workflow secrets is capped at 1,000 characters. Secrets are read with `process.env.NAME`.
- **Workflows:** up to 50 simple on Starter, up to 300 fully customisable on Professional.
- **Never write to a property a human maintains.** Use prefixed properties (`rc_*`) and promote with a separate workflow only where the human field is empty.

**HubSpot custom code action (Node 20):**

```javascript
// Input field: email   Output fields: rc_status, rc_title, rc_company, rc_headcount
// Secret: RC_API_KEY
const axios = require('axios');

exports.main = async (event, callback) => {
  const email = event.inputFields['email'];
  const res = await axios.post(
    'https://api.reversecontact.com/v2/enrich/persons',
    { email },
    { headers: { Authorization: `Bearer ${process.env.RC_API_KEY}` } }
  );

  const person = res.data?.data?.person;
  const company = res.data?.data?.company;

  // null means "not found", not "try harder". Write nothing and flag it.
  if (!person) return callback({ outputFields: { rc_status: 'no_match' } });

  callback({ outputFields: {
    rc_status:    'matched',
    rc_title:     person.currentPosition?.title || '',
    rc_company:   company?.name || '',
    rc_headcount: company?.employeeCount || 0
  }});
};
```

Docs: https://developers.hubspot.com/docs/api/overview

### n8n

- **Base:** `Self-hosted or n8n Cloud`
- **Auth:** Credentials are stored in n8n, not in the workflow JSON, so the workflow stays safe to export and review.

| Call | Request | What it does |
|---|---|---|
| `NODE HTTP Request` | `Authentication: Generic > Header Auth. Name: Authorization. Value: Bearer rc_your_api_key` | There is no dedicated Reverse Contact node and you do not need one. Five minutes to configure, and no node update can break it. |
| `NODE HubSpot Trigger` | - | Authenticates with a **developer API key from a HubSpot developer account**, not a private app token, because that is how HubSpot exposes the webhooks API. Free to create, and nobody expects it. |
| `NODE Wait + IF` | - | The polling loop for Reverse Contact's /live endpoints: Wait 5s, GET the webhook id, IF status != succeeded loop back. |

**Rules that will cost you time if you skip them:**

- HubSpot allows **one webhook URL per app**. Route several object types through one subscription and branch inside n8n with a Switch node.
- Self-hosting is usually the reason this route was chosen: records never leave infrastructure you control. Do not quietly move it to a third-party cloud.
- n8n must be reachable by HubSpot for webhook triggers to fire.

Docs: https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest

## Build it

### 1. Cluster locally first, and pay nothing for it

Group records that might match: same email domain and surname, same profile URL, same normalised name at the same company. This is free, and it is what keeps the resolution step affordable. Resolving every record in the database is the naive version and costs an order of magnitude more.

### 2. Resolve each candidate to an identity

Two CRM rows resolving to the same canonical identity is a far stronger signal than two rows with similar names. This is the entire reason to do it this way rather than with a fuzzy match.

### 3. Threshold, do not judge

Set a confidence bar above which merges are proposed and below which a human looks. The API returns null with a confidence score instead of a best guess, and the precision threshold can be raised on the request. Fuzzy matching gives you a similarity number with no contract behind it.

### 4. Dry run, and export it

Report-only mode. Export the proposed merges with both records side by side and the confidence attached. Have somebody who knows the accounts read a hundred of them. This is not optional and you should refuse to skip it.

### 5. Write the merge rules down before merging

Which record survives. Which fields win. What happens to a conflicting owner. What happens to the activity history on the losing record. All of it decided in advance, because this is the step you cannot walk back.

### 6. Fix the intake, or schedule this forever

Duplicates re-accumulate through the same doors: forms, imports, manual creation. One pass is not a solution.

## Gotchas

- Merging is close to irreversible, and the damage is silent: a lost activity history looks exactly like a contact who was never engaged.
- Personal email addresses resolve badly, and they are on exactly the records most likely to be duplicated. Route those to review rather than lowering the threshold.
- The technical merge is easy. Deciding which rep keeps the relationship is a conversation with sales leadership, and it should happen before the dry run rather than after somebody notices.
- Keep the dry-run export. It is your record of what happened and the only way to answer "what did this do to my record?" later.

## What breaks, from the vendors' own docs

- **Merging is close to irreversible.** Most CRM merges cannot be cleanly undone, and the damage is silent: a lost activity history looks exactly like a contact who was never engaged. Treat the dry run as part of the build rather than as a nice-to-have, and keep the export as your record of what happened.
- **Identity resolution is not a name match.** That is the point, and it is also a limit. Two records for the same person at different companies over time are the same identity, and whether you want them merged is a policy question rather than a data one. Decide before you build which of those cases is a duplicate and which is a history.
- **Personal email addresses resolve badly.** A work email is a strong identity signal; a personal one often is not. Expect a lower resolution rate on the exact records most likely to be duplicated, and route those to review rather than pushing the threshold down to catch them.
- **Owners and activity are the real fight.** The technical merge is easy. Deciding which rep keeps the relationship, and what happens to the activity attached to the losing record, is a conversation with sales leadership. Have it before the dry run, not after somebody notices.
- **One pass is not a solution.** Duplicates re-accumulate through the same doors they came in: forms, imports, and manual creation. Fix the intake as well, or schedule this and accept it as a standing cost.

## How to verify it works

- Run the clustering and confirm the candidate count is a small fraction of the database.
- Run the dry run and read a hundred proposed merges with someone who knows the accounts.
- Confirm a known same-person-different-company pair is handled the way the policy decision said, not merged by accident.
- Merge ten, then check the surviving records kept the activity history from both.
- Re-run the clustering a month later to see how fast duplicates are re-accumulating. That number tells you whether the intake needs fixing.

## What this costs to run

| Component | Billing | What drives it |
|---|---|---|
| HubSpot | Any tier | Reads and merges through the API, which is free on every tier. The orchestration sits outside HubSpot. |
| Reverse Contact | Per credit | One call per candidate record, not per CRM record. Clustering first is what keeps this affordable. |
| n8n | Free self-hosted | The right home for this: a long-running job with a dry-run mode, a review queue and an audit trail you control. |
| Human review | An afternoon | The line nobody budgets and the one that prevents the expensive mistake. |

The lever on this bill is the clustering step. Resolving every record in the database is the naive version and costs an order of magnitude more than resolving only the records that already look like candidates.

## Sources

- Reverse Contact: https://docs.reversecontact.com/getting-started
- HubSpot: https://developers.hubspot.com/docs/api/overview
- n8n: https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest
- This workflow, with the reasoning behind each step: https://www.reversecontact.com/integrations-hub/workflows/crm-deduplication

---

*Published by Reverse Contact, which appears in this directory as a data provider.
No other vendor pays for placement. Where a vendor publishes no public figure, this file says so
rather than estimating. Reverse Contact costs are stated in credits, which it publishes; no dollar
rate per lookup appears here, because none is published and dividing a pack price is not their number.*
