---
name: crm-data-layer-loop
description: Build a scheduled enrichment loop over a CRM: pull the records missing a field, fill the gaps with Reverse Contact, write back without overwriting anything a human owns, and run it on a cadence. Use when the user wants to backfill or maintain CRM firmographics, fix partial records at scale, or stop lead scoring falling back to defaults.
---

# The CRM data layer

> Generated from https://www.reversecontact.com/integrations-hub/workflows/crm-data-layer
> 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, Clay, Reverse Contact, n8n.
**Build effort:** Days.

## What you are building

A loop rather than a backfill. Pull the filtered slice of records missing something, resolve each one, write the result to dedicated properties, promote into the trusted fields only where they are empty, and re-run on a schedule so the fields stop hollowing out again.

## Ask this before writing anything

Who owns the enrichment logic, and how often does it change? If an engineer owns it and it is stable, build it in n8n: cheaper, one meter, no table. If a non-engineer owns it and it changes monthly, build it in Clay: the table is the product and the actions are worth it. Do not build both. Re-ask this in six months, because paying two meters for a pipeline nobody has touched is the standing failure mode.

## Prerequisites

| What | Where to get it | Notes |
|---|---|---|
| Reverse Contact API key | Workspace > API Keys | Credits are consumed per gap row, not per CRM record |
| CRM access with write scope | A HubSpot private app, or a Salesforce connected app | HubSpot needs no Data Hub here: the calls happen outside HubSpot |
| Clay workbook or an n8n instance | Whichever the decision above picked | Clay needs a plan that allows HTTP API columns |

## 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

### Clay

- **Base:** `Configured in the table, not through an API`
- **Auth:** Per-integration, set in the workbook.

| Call | Request | What it does |
|---|---|---|
| `ACTION HubSpot / Salesforce Lookup` | - | Read-only. Pulls records into the table and changes nothing in the CRM. |
| `COLUMN HTTP API` | `POST https://api.reversecontact.com/v2/enrich/persons\nHeaders: { "Authorization": "Bearer rc_...", "Content-Type": "application/json" }\nBody: { "email": "/Work Email" }` | `/Work Email` is a column reference, so each row posts its own value. This is how a provider with no native listing becomes a column. |
| `ACTION HubSpot / Salesforce Update` | - | Writes back. Immediately live to every CRM user. Turn on "ignore blank values" and exclude rep-owned properties. |

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

- **Clay bills per action on the attempt, not the result.** Effective cost per filled field is the action rate divided by your match rate. Order a waterfall cheapest-first and use conditional runs so the expensive source only sees the residue.
- Import a filtered slice, never the whole portal. Filter on the gap you are filling.
- Run read-only until the columns look right, write to ten rows, open them in the CRM, and only then schedule.

Docs: https://university.clay.com/docs/hubspot-integration-overview

### 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. Write down the gap, then query for it

Not "all contacts". Contacts with no title. Companies with no employee count. Anything not touched in 12 months. Use the CRM search endpoint with a filter, and count the result before you spend anything: in most CRMs the gap is an order of magnitude smaller than the database, and that difference is the whole bill.

### 2. Read only, first

Pull the slice into a Clay table or an n8n batch and look at it. Do not connect a write step yet. This is the step that gets skipped and the reason dedupe and enrichment projects become incidents.

### 3. Enrich, conditionally

One call per gap row. If you are running a waterfall, the cheapest broad source goes first and Reverse Contact runs only where that came back empty, or the other way round depending on your measured match rates. Branch on the confidence score, not on whether a field is non-empty.

### 4. Write to prefixed properties with blanks ignored

Turn on "ignore blank values" so an empty response never blanks a populated field, and keep an explicit exclusion list of the properties reps maintain. Then write **ten rows** and open them in the CRM by hand.

### 5. Promote with a separate rule

A CRM workflow copies the enriched value into the trusted field only where that field is empty. Two systems writing the same field is two systems disagreeing on a schedule.

### 6. Pick a cadence per field, not one for everything

Weekly for records on an open opportunity, quarterly for the rest, annually for firmographics on dormant accounts. One cadence across everything either burns credits refreshing fields that did not move, or runs your routing on last quarter's data.

## Gotchas

- Clay bills the attempt, not the result. Effective cost per filled field is the action rate divided by your match rate, so a hard segment can cost three or four times the headline.
- A Clay Update is immediately live to every CRM user. There is no staging environment.
- Nobody publishes a match rate you can hold them to, including Reverse Contact, whose 70%+ figure is global rather than a promise about your list. Run 500 of your own rows and count.
- On Salesforce, validation rules and triggers will reject writes that HubSpot would accept, and a completed run is not a successful write. Read the per-record errors.

## What breaks, from the vendors' own docs

- **Clay bills the attempt, not the result.** An action is consumed whether or not anything comes back, so your effective cost per filled field is the action rate divided by your match rate. On a hard segment that multiplier is three or four. This is the single biggest driver of the bill and it is entirely controlled by how tightly you filter the slice you import.
- **A write is immediately live to everyone.** There is no staging environment between a Clay Update and your reps. Ten rows, opened by hand in the CRM, before anything is scheduled. Every unpleasant version of this story starts with somebody skipping that step because the columns looked right.
- **Importing the whole portal is the classic mistake.** It spends actions on rows that needed nothing, makes the write step far more dangerous, and produces a bill that bears no relation to the value delivered. Filter to the gap, always.
- **Nobody publishes a match rate you can hold them to.** Including Reverse Contact, whose 70%+ identity match rate is a global figure rather than a promise about your list. Run 500 of your own rows and count. That number, not anyone's marketing, is what predicts both your coverage and your bill.
- **The refresh cadence is a decision, not a default.** Weekly is right for an active pipeline and wasteful for a dormant database. Pick the cadence from how fast the field actually goes stale: job titles move quarterly, headcount annually, and email addresses somewhere in between.

## How to verify it works

- Run the query for the gap and record the count. It should be far smaller than the total record count; if it is not, the filter is wrong.
- Write ten rows, then open each one in the CRM and confirm no rep-owned field changed.
- Deliberately include a row you know will not resolve. Confirm nothing was written to it rather than a blank overwriting a populated field.
- Run the promote workflow and confirm it only filled empty trusted fields.
- Re-run the gap query a day later. The count should have fallen by roughly your match rate, and that number is what you report.

## What this costs to run

| Component | Billing | What drives it |
|---|---|---|
| HubSpot | Any tier | This workflow does not need Data Hub, because the API calls happen outside HubSpot. Free CRM API access is on every tier. |
| Clay | Per action | Rows imported multiplied by enrichment columns, whether or not they resolve. The lever is the filter on step one. |
| Reverse Contact | Per credit | One call per gap row, 2 credits for a reverse lookup from an email. Packs from $100, valid 3 months, or unmetered on an Unlimited plan that covers the endpoint. |
| n8n | Free self-hosted | Optional. A small instance, and your own uptime. |

The honest way to size this is bottom-up. Count the records actually missing the field you care about, not the size of your database. In most CRMs those two numbers differ by an order of magnitude, and the second one is the one people quote in budget meetings.

## Sources

- Reverse Contact: https://docs.reversecontact.com/getting-started
- Clay: https://university.clay.com/docs/hubspot-integration-overview
- 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-data-layer

---

*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.*
