---
name: hubspot-reverse-contact-integration
description: Connect HubSpot and Reverse Contact: what syncs, which editions carry it, the setup order, and the failures to expect. Covers contacts, companies. Use when the user wants to set up, audit or troubleshoot HubSpot and Reverse Contact together, or asks why data is not moving between them.
---

# HubSpot and Reverse Contact

> Generated from https://www.reversecontact.com/integrations-hub/hubspot-integrations/hubspot-reverse-contact-integration
> Every tier requirement, sync direction and limit below was read from the vendors' own documentation on 2026-10-11.
> Vendors change these without notice. Re-check anything load-bearing before you rely on it.

**What you have to buy first:** A Reverse Contact API key. The in-HubSpot route needs Data Hub Professional.

**What moves:** contacts, companies, one way, into HubSpot.
**How it is built:** built on the api, zapier, make or n8n, mcp server. **Effort:** hours.

## The short version

Give it an email, a domain or a profile URL and it returns the person, their current role and the company behind it on one schema, which is what makes it safe to write into HubSpot properties rather than into a notes field somebody reads later. Four routes get it there, and the one people assume is cheapest usually is not: calling the API from inside a HubSpot workflow needs Data Hub Professional, because both the webhook action and the custom code action live in that hub rather than in Sales Hub. If you already own Data Hub, that route is the cleanest thing on this page. If you do not, Clay and n8n are not the fallback, they are the answer, and they cost less than the hub upgrade by a distance.

## Which HubSpot licence can call an outside API

Rows: What you own in HubSpot. Columns: How you would call the API. The only question on the HubSpot side of this pair is whether you own Data Hub, and the grid is almost all one answer. Three of these five rows are identical, which is the finding rather than a formatting accident: upgrading Sales Hub buys nothing here, because the two actions that can reach an outside API live in a different hub altogether.

| What you own in HubSpot | A webhook action in a workflow | A custom code action in a workflow | The native Clay, Zapier or Make app | An n8n workflow on the CRM API |
|---|---|---|---|---|
| Free CRM or Starter | Not available | Not available | Available | Available |
| Sales Hub Professional, no Data Hub | Not available | Not available | Available | Available |
| Sales Hub Enterprise, no Data Hub | Not available | Not available | Available | Available |
| Data Hub Professional | Available | Available | Available | Available |
| Data Hub Enterprise | Available | Available | Available | Available |

- **Available.** Available on that line. Full CRM API access is on every HubSpot tier including the free one, which is why all three external routes work everywhere: Clay, Zapier, Make and n8n read and write through that API rather than through a workflow.
- **Not available.** Not available at any price on that line. HubSpot documents both the webhook action and the custom code action as requiring Data Hub Professional or Enterprise, and sells Data Hub separately from Sales Hub, so this is a licence conversation rather than a settings one.

Counted off that grid, of twenty pairings: fourteen give you available, six give you not available.

Read down the first two columns and the recommendation writes itself. If you own Data Hub, call the API from a workflow and stop there, because it runs where the data already is and there is no third vendor to meter it or to break. If you do not, buying a hub to avoid a middle layer is the expensive answer: a Clay table or an n8n workflow does the same job against the CRM API that every tier already carries.

## What actually syncs

Direction is written from HubSpot's point of view: out means out of HubSpot, in means into it.

| What | Direction | What that means in practice |
|---|---|---|
| Email to full person record | One way, in | POST /v2/enrich/persons resolves an email into identity, current role, history, education, skills and location. |
| Domain to company record | One way, in | POST /v2/enrich/companies returns firmographics and metadata for a domain or company name. |
| Live resolution | One way, in | The /live endpoints return a task id. Poll GET /v2/webhooks/:webhookId until status is succeeded, which is free and off the rate-limit clock. |
| Anything back to Reverse Contact | One way, out | Nothing. This is a read layer. Your pipeline decides what reaches HubSpot properties. |

## Which field lands where

There is no field mapping screen here, because there is no app to hold one. What decides the shape of this build is which HubSpot feature carries the call, and the properties the answer lands in are ones you create and name.

| In HubSpot | In Reverse Contact | What to know about the match |
|---|---|---|
| Contact email | POST /v2/enrich/persons, 2 credits | The usual starting point, because a form submission carries an email and nothing else. Returns identity, the current role, history, education, skills and location on one schema, which is what makes it safe to write into typed properties. |
| Company domain | POST /v2/enrich/companies, 2 credits | Firmographics from a domain or a company name. Run it on the company record rather than once per contact: one call covers every contact associated with it. |
| A profile URL already on the contact | POST /v2/fetch/persons, 1 credit | Half the price, and unmetered from the $249 plan rather than the $699 one. If any part of your stack already captures a profile URL, routing those contacts to this call instead is the largest single saving available on this pair. |
| A free freshness check first | POST /v2/fetch/persons/check, 0 credits | Says whether a profile is cached and when it was last updated, so the workflow chooses a 1-credit read or a 2-credit live refresh on evidence. Free in credits, and one more call inside the same 20 seconds. |
| A workflow secret | process.env.RC_API_KEY | Secrets are managed in the action definition and arrive as environment variables. The total length of all secret values in one action is capped at 1,000 characters. |
| require("axios") in a custom code action | The HTTP call itself | HubSpot pre-loads axios at ^1.2.0 among twelve Node libraries, including @hubspot/api-client at ^10 and lodash, so the action needs no dependency management of its own. |
| The callback() function | Output fields the workflow branches on | The documented way to pass data back into the workflow, and Node.js only. Return a match status alongside the values, because the workflow cannot otherwise tell a miss from a hit. |
| Anything outbound to Reverse Contact | Nothing at all | This is a read layer. No HubSpot property, contact or event is sent anywhere, and there is nothing in the product to send it to. |

### Three documented behaviours that change how the enrichment is written

These are HubSpot's own caveats about custom code actions rather than anything to do with enrichment, and each one works perfectly in a test on a single contact. The first is a correctness problem rather than a performance one, which is why it leads.

| What HubSpot documents | What it means for an enrichment action |
|---|---|
| Variables declared outside exports.main may be re-used by future executions | A response held in a module-level variable can be served to the next contact. Everything about a person belongs inside exports.main |
| A rate-limited call is retried only if you throw the error in the catch block | A 429 caught and turned into a tidy no_match is a contact silently left un-enriched, with the workflow reporting success |
| Actions must finish within 20 seconds and 128 MB | Comfortable for a cached lookup against a published 500ms P95. Impossible for a live refresh, which answers with a task rather than a record |
| The total length of all secret values is capped at 1,000 characters | One API key is nowhere near it. Worth knowing before a second and a third integration share the same action |
| Math.random is seeded by the current time, so executions can repeat | Only matters if you are sampling rows. HubSpot pre-loads random-number-csprng for the case where it does |
| Test logs report memory used and total runtime | The only place the distance to those two ceilings is visible, so read them before the workflow goes live rather than after |

**What does not cross:**

- An App Marketplace listing. There is none, which is consistent rather than an oversight: Reverse Contact maintains apps on Clay, Zapier and Make and nothing inside any CRM or sequencer.
- The live endpoints, from a workflow. They answer with a task id, a custom code action has 20 seconds, and Reverse Contact documents a live job as usually seconds and possibly tens of minutes.
- Output fields from a webhook action. The documented route for passing data back into a workflow is the callback() function in a custom code action, which is why every example on this page uses that one.
- A business email or a direct phone number. Both are separate endpoints at 3 and 20 credits, charged only when one is found, and the email finder is asynchronous as well.

## Connect it, in this order

**Who has to do it:** A HubSpot Super Admin for the route that lives inside HubSpot, or whoever owns the Clay workbook or the n8n instance for the routes that do not. Plus whoever can create a Reverse Contact API key.
**How long:** An afternoon once the licence question is settled. The licence question itself can take a week, which is why it is step one.

### 1. Find out whether you own Data Hub, before you design anything

*Where:* HubSpot: Settings, Account and Billing

Both the webhook action and the custom code action require Data Hub Professional or Enterprise, which HubSpot sells separately from Sales Hub. A team on Sales Hub Professional has workflows and still cannot call an outside API from one. This is the most expensive surprise on the pair and it is a purchase rather than a setting.

### 2. Pick the route that matches what you actually own

*Where:* The five routes on this page

With Data Hub, a custom code action inside a workflow is the cleanest thing here. Without it, Clay and n8n are not a fallback, they are the answer, and both cost far less than the hub. Deciding this before you build means not discovering the gate halfway through a Flow somebody has already demoed.

### 3. Create the properties the enrichment is allowed to own

*Where:* HubSpot: Settings, Properties

Prefix them, so no rep ever types into one. Nothing in this build decides for you which property a value lands in, which is more work than a marketplace app and is also the reason this route never flattens a field somebody maintains by hand.

### 4. Store the key as a workflow secret, not in the code

*Where:* HubSpot: the custom code action, Add secret

Secrets are managed in the workflow action definition and arrive in the code as environment variables, read with process.env. The one documented ceiling is that the total length of all secret values in an action must not exceed 1,000 characters, which one API key will not trouble and three might.

### 5. Write the no-match branch before the one that writes

*Where:* HubSpot: callback() output fields

Reverse Contact returns null with a confidence score rather than a best guess, so a lookup that matched nobody is a normal outcome. Return a status through callback() and branch the workflow on it, rather than letting the write action run with nothing to write.

### 6. Keep every person-shaped variable inside exports.main

*Where:* HubSpot: the custom code action

HubSpot documents that variables declared outside exports.main may be re-used by future executions of the action, to save memory. For an enrichment action that means one contact can be served another contact's response. Only a connection you genuinely want re-used belongs outside the function.

### 7. Re-throw rate limits rather than swallowing them

*Where:* HubSpot: the catch block

HubSpot only retries a rate-limited call if you throw the error in the catch block in Node.js, or raise it in the except block in Python. A 429 caught and turned into a tidy no_match is a contact silently left un-enriched while the workflow reports success.

### 8. Test one contact and read the logs rather than the output

*Where:* HubSpot: the action, Test

The test logs report how much memory the action used and its total runtime, which are the two numbers the 20-second and 128 MB ceilings are measured against. The output tells you the enrichment worked on one contact, which was never the thing in doubt.

The first step is the whole page and the other seven are an afternoon. That asymmetry is unusual here: on [Salesforce the question is architectural](pair:salesforce+reverse-contact), about callout ceilings and where a backfill lives, while on HubSpot it is a line on an invoice.

## How to check it worked

- Run the action on a contact whose answer you know, then on an address that resolves to nobody. The second is the test: the workflow should take the empty branch, write nothing, and spend no credits.
- Read the test log for memory used and total runtime on a real contact. If a cached lookup is anywhere near 20 seconds, something other than the enrichment is slow and it will not survive a list import.
- Set the secret to a deliberately wrong key once and watch what the action does with the 401. If it reports success and writes nothing, your error handling is the thing that needs fixing rather than the key.
- Enrol two contacts at once rather than one, and confirm each got its own answer. That is the only test that catches the variable re-use caveat, and a single-contact test never will.

## When it goes wrong

Each row is a symptom somebody reports, the documented reason, and the fix. Work down it before escalating to either vendor, because most of these are configuration.

| Symptom | Why it happens | What to do |
|---|---|---|
| There is no webhook action in the workflow editor | Both the webhook action and the custom code action require Data Hub Professional or Enterprise, which HubSpot sells separately from Sales Hub. Workflows themselves are a Sales Hub feature and reaching outside them is not. | Price the hub against Clay and n8n before buying it. Full CRM API access is on every tier including the free one, so an external route reads and writes the same records without the upgrade. |
| The custom code action timed out | An action must finish within 20 seconds and inside 128 MB of memory, and HubSpot returns an error on exceeding either. | Use the cached endpoints, which publish a 500ms P95. Arriving near 20 seconds means you are either calling a live endpoint, which answers with a task rather than a record, or looping over records inside one action. |
| One contact was written another contact's job title | HubSpot documents that variables declared outside exports.main may be re-used by future executions of the action, to save memory, and many objects can be enrolled at the same moment. | Move every variable holding anything about a person inside exports.main. Only a connection you intend to re-use belongs outside it, which is the case the caveat was actually written for. |
| Some contacts were quietly left un-enriched | A rate-limited call is only retried if the error is thrown. HubSpot documents that in Node.js you must throw it in the catch block, and in Python raise it in the except block. | Re-throw on a 429 instead of returning a no_match. A swallowed rate limit looks exactly like a real miss in the workflow history, which is what makes this one expensive to find later. |
| A property a rep maintained has been overwritten | Nothing in this build decides that for you. The API returns a record and the property it lands in is whichever one your action names. | Write to prefixed properties only, then promote a value into a human-maintained property with a separate workflow that fires only where the human property is empty. |
| The workflow reports success and the property is empty | Reverse Contact returns null with a confidence score rather than a best guess, so a lookup that matched nobody completes normally rather than failing. | Return a match status from callback() as its own output field and branch the workflow on it. The call itself cost nothing, because every 4xx and 5xx is free. |
| Everything stopped at once, including the calls that were free | Below 2 credits the free Check endpoints are paused too and answer 402 NO_CREDITS, because the fetch a check precedes can itself cost 2. | Read quotas.workspace.credits.left from any response and alert on it. GET /v2/usage keeps answering when the checks do not, so a balance check never fails for the reason the lookup did. |
| An endpoint that worked last week returns nothing | /v2/resolve was replaced by /v2/enrich and /v2/search/persons by /v2/search/people, with the old pair documented as live only until 13 October 2026. | Open the custom code action and change the path. A workflow action is not version-controlled by default, so the only copy of that string is the one inside it, and nothing will warn you. |

## What breaks, from the vendors' own docs

- **There is no app inside HubSpot.** As of 11 October 2026 Reverse Contact has no listing on the HubSpot App Marketplace. It maintains apps on Clay, Zapier and Make, so the shortest route is a step in one of those rather than anything installed in HubSpot. That is an afternoon of work, not a quarter, but it is not a click inside the CRM.
- **The in-HubSpot route is a Data Hub feature.** Both the webhook action and the custom code action in workflows require Data Hub Professional or Enterprise, which HubSpot sells separately from Sales Hub. A team on Sales Hub Professional cannot call an external API from a workflow at all. Price the hub before you design around this route, because it is usually more than Clay and n8n cost together.
- **Custom code has 20 seconds and 128 MB.** HubSpot caps a custom code action at 20 seconds of execution and 128 MB of memory. A cached enrichment call fits comfortably. The live endpoints, which return a task to poll, do not, which is why live resolution belongs in n8n rather than in a workflow.
- **Nothing writes back on its own.** The API returns a record. Deciding which HubSpot property it lands in, and whether it may overwrite what is there, is your pipeline's job. That is more work than a marketplace app and it is also the reason this route never flattens a field a rep owns.
- **The credit cost is published, the dollar rate is not.** Each call has a published credit price: 2 for a reverse lookup from an email, 1 for a cached lookup, 2 for a live refresh, free for a freshness check. What a credit costs depends on the pack or plan it came from, the full matrix sits in the dashboard rather than on the pricing page, and credit packs now expire after 3 months. Any cost model here states credits and leaves the conversion to your own plan.
- **Live resolution is asynchronous.** The live endpoints hand back a task rather than a record. A HubSpot workflow webhook cannot wait for that, so either use the cached endpoint in the workflow or run the live path in n8n where you can poll.

## The APIs, if you are building around it instead

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

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

## Sources

- Reverse Contact API documentation: https://docs.reversecontact.com/getting-started
- Reverse Contact: credits: https://docs.reversecontact.com/guides/credits
- Reverse Contact: rate limits: https://docs.reversecontact.com/guides/rate-limits
- Reverse Contact: MCP delivery method: https://www.reversecontact.com/delivery-method/mcp
- Reverse Contact pricing: https://www.reversecontact.com/pricing
- HubSpot developers: custom code workflow actions: https://developers.hubspot.com/docs/api-reference/legacy/automation/workflow-actions/custom-code-actions
- 14 practitioner threads read on 2026-10-11, summarised on the page: https://www.reversecontact.com/integrations-hub/hubspot-integrations/hubspot-reverse-contact-integration#reddit
- This pair, with the reasoning behind each step: https://www.reversecontact.com/integrations-hub/hubspot-integrations/hubspot-reverse-contact-integration

---

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