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

# HubSpot and Clay

> Generated from https://www.reversecontact.com/integrations-hub/hubspot-integrations/hubspot-clay-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:** Clay Growth or above, where CRM integrations start. Nothing extra on HubSpot.

**What moves:** contacts, companies, deals, lists, both ways.
**How it is built:** native, built on the api. **Effort:** hours.

## The short version

Price the Clay plan before anything else, because CRM integrations start on Growth and the HubSpot integration documentation never mentions it. Past that, this is a loop rather than a sync and the framing matters: Lookup actions read without changing anything, while Create and Update write a result every user in the portal sees immediately. The discipline that keeps it safe is the same three rules every time: import a filtered set rather than the portal, keep blank values ignored, and exclude the properties your reps own.

## The Clay plans that actually carry this

Rows: Clay plan. Columns: What the loop needs. HubSpot gates almost nothing here. Clay gates most of it, and its own HubSpot documentation does not mention a plan, so this grid is read off the pricing page instead.

| Clay plan | Scheduled runs | CRM integrations | HTTP API and webhooks | Sync faster than daily |
|---|---|---|---|---|
| Free | No access | No access | No access | No access |
| Launch | Full access | No access | No access | No access |
| Growth | Full access | Full access | Full access | No access |
| Enterprise | Full access | Full access | Full access | Full access |

- **No access.** The row on Clay's plan comparison reads "Not included". For CRM integrations that means the HubSpot source and the object actions are not available to you at all, whatever HubSpot edition you are on.
- **Full access.** The row reads "Included". Source sync frequency is the one that is not binary: it is one day on Free, Launch and Growth, and 15 minutes on Enterprise.

Counted off that grid, of sixteen pairings: eight give you no access, eight give you full access.

The staircase is the useful shape here, and it runs the opposite way to most pairs in this directory: a HubSpot upgrade buys Clay almost nothing, and the plan that decides whether this pair exists at all is Clay's. If the bill is the problem, the lever is the filter on the import step rather than a tier on either side.

## 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 |
|---|---|---|
| HubSpot to Clay | One way, in | Lookup actions pull contacts, companies, deals or a list into a table. Read-only, so nothing in HubSpot changes. |
| Enrichment in between | Events only | Any provider, including any HTTP API, becomes a column. This is how a tool with no HubSpot app gets one. |
| Clay to HubSpot | One way, out | Create and Update push real changes. Test on a handful of rows first, because there is no preview of a write at volume. |
| Refresh | Two-way sync | Auto-update re-runs the table on a schedule, which is what turns a one-time backfill into a maintained field. |

## Which field lands where

Clay does not map fields to HubSpot so much as read and write them one action at a time. Every action starts with an object type pulled from your own portal, and the properties underneath change with the type you pick, so the dropdown is your schema rather than a fixed list.

| In HubSpot | In Clay | What to know about the match |
|---|---|---|
| Contacts | Look up, Create, Update object | Reading needs crm.objects.contacts.read, which is mandatory. Writing needs the contacts write scope, which is optional and on by default, so a connection made with it unticked reads perfectly and silently cannot write. |
| Companies | The same three, plus a domain switch | Keep subdomains in Company domain is off by default on Create and Update, so shop.example.com is reduced to example.com before it is written. Look up has the matching switch for its Domain filter and the two are set separately. |
| Deals | Look up, Create, Update object | The deal read and write scopes are optional and enabled by default. Choosing Deal as the object type exposes your own pipelines and their stages as mappable fields. |
| Leads | Create object, with Association Fields | Lead is the one type whose Create action associates as it creates, taking an association object type of Company or Contact, an association type, and the target object ID. |
| Owners | Find owner | By owner ID or by email, and supplying both validates the email against the owner found by ID. Clay says the ID is the more reliable input, because an email coming out of an enrichment often belongs to nobody in the portal. |
| Associations | Create association, Get associated objects | Get associated objects defaults to 20 and 20 is also the maximum, so a company with fifty contacts cannot be read in one call. |
| Static lists | Add record to list | Only lists whose membership you can edit are offered. HubSpot recalculates an active list from its own filters, so those never appear in the dropdown and the list has to be created as static first. |
| Custom objects | Every object action, Enterprise only | They appear in the object type dropdown after the standard four. The three scopes behind them are the ones HubSpot will not grant below Enterprise. |

### What each Clay write looks like from inside HubSpot

| The action | How it reads on the record |
|---|---|
| Update object | A property change on the existing record, visible to every user at once, with no staging copy and no preview |
| Create object | A new record, and a duplicate of one that already existed under a key you did not match on |
| Create association | A link between two records, of the association type the pair of object types offered |
| Add record to list | Membership of a static list, or nothing at all with Added to list returned as false |
| An enrichment you did not map | Nothing. A column that stays in the table is invisible to the portal, and it still cost an action |

**What does not cross:**

- Activity. The action list covers objects, associations, owners and lists, and carries nothing that writes to a timeline, so an email Clay found is a property value rather than a line on the record.
- Any marker saying a table did it. A Clay write is a property change like any other and shows in HubSpot's own property history as one. Writing to prefixed properties is how teams tell their enrichment from their reps.
- Active list membership, which is HubSpot's to compute from the list's filters rather than anybody's to write.

## Connect it, in this order

**Who has to do it:** Somebody who can authorise an app on the HubSpot portal, and whoever owns the Clay workbook. One person is often both.
**How long:** Ten minutes to connect. The hour goes on deciding what to import and what to let it write.

### 1. Check the Clay plan before anything else

*Where:* Clay: pricing

The plan comparison marks CRM integrations as a Growth feature, not on Free or Launch, and Growth is $446 a month on the page header. Nothing in the HubSpot integration documentation says so, so this is the step that gets skipped and the one that ends the project.

### 2. Build the static list before you connect

*Where:* HubSpot: Lists

Clay's import takes an optional list, and the documented behaviour without one is that every object is pulled. A static list of the records missing the field you care about is the difference between four hundred rows and the whole portal, and it sets what the run costs.

### 3. Connect the account from inside a workbook

*Where:* Clay: workbook, + Add

Click + Add at the bottom of a workbook, search HubSpot, then pick the account or run + Add account. Seven read scopes are mandatory and cannot be refused: contacts, companies, leads, owners and lists, plus the contact and company property schemas.

### 4. Leave the three custom object scopes off below Enterprise

*Where:* Clay: the consent screen

crm.schemas.custom.read, crm.objects.custom.read and crm.objects.custom.write arrive switched off, and Clay documents why: HubSpot grants them on Enterprise portals only, and authorisation stops rather than continuing without them. Switch them on below Enterprise and the connection fails outright.

### 5. Import the filtered slice as the table source

*Where:* Clay: Import objects from HubSpot

The object type list is read from your own portal, so your custom objects sit beside the standard ones. Point it at the list, leave Include Read Only Properties off so you get editable properties rather than every calculated field, and turn Exclude empty properties on if blanks are noise.

### 6. Run the read columns and look at them

*Where:* Clay: Add enrichment

Look up object, Get associated objects and Find owner all read and change nothing in HubSpot. Run the table to the end of those columns and check the values while a mistake is still free, because the next step is not reversible.

### 7. Write with Update keyed on the HubSpot record ID

*Where:* Clay: Update object

Update requires the HubSpot Object ID, and that requirement is what makes the write land on the existing record instead of spawning a copy. Ignore blank values is on by default and should stay on. Create belongs to records that are genuinely new.

### 8. Put it on Auto-update with a condition

*Where:* Clay: run settings

Auto-update re-runs the table and Only run if holds a column back until its condition is met. That pair is what turns a backfill into a maintained property, and what stops every provider re-running against rows that already resolved. Source sync is daily on every plan below Enterprise, where it is 15 minutes.

Six of those eight steps are reversible and two are not. The plan check comes before the build rather than after it, and the filter comes before the import rather than after a bill. The write step is the one worth rehearsing on ten rows, which is the discipline this part of the [orchestration layer](layer:orchestrate) rewards more than any other.

## How to check it worked

- Open three of the records you wrote to and read the property values in HubSpot against the Clay column. A write is live for every user in the portal the moment it lands, so this is the only preview there is.
- Run the import twice and count the records. If the second run creates rather than updates, the write is on Create instead of Update keyed on the record ID.
- Read the Added to list output on a handful of rows rather than the row status. A row can succeed with that output false, which means HubSpot took the request and declined the record.
- Set the lookup Limit deliberately. It defaults to 10 and caps at 200, so an action that looks like it is missing matches may simply have stopped counting.

## 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 |
|---|---|---|
| The HubSpot source and the object actions are not there | The workspace is on Free or Launch. Clay's plan comparison marks CRM integrations as included from Growth, and nothing in the HubSpot integration documentation repeats it. | Check the plan before debugging the connection. There is no partial version of this on a lower tier, so the decision is a purchase rather than a setting. |
| Connecting fails with an unexpected error during the app authorization process | One of the three custom object scopes was switched on against a portal below Enterprise. HubSpot cannot grant them there, and the authorisation stops rather than proceeding without them. | Reconnect with all three off, which is how they arrive. Reconnecting keeps whatever was enabled last time, so an Enterprise portal that already has them on holds onto them. |
| The List dropdown shows an error asking you to reconnect | The connection does not carry the create and edit lists permission. HubSpot asks for it by default, so this is a connection somebody made with it unticked. | Reconnect the account and select that scope. It is the same flow and the rest of the permissions are unaffected. |
| A row ran, HubSpot accepted it, and the record is not in the list | Added to list came back false. Clay documents that as HubSpot taking the request and declining the record, because it is already a member or is not eligible for that list. | Read the output rather than the row status. A record ID that does not exist in the portal fails the row instead, which is a different signal and a different fix. |
| The write created a second copy of a record that already existed | Create was used where Update was meant. Create has no record ID input and no matching step, so it writes a new object every time it runs. | Use Update keyed on the HubSpot Object ID for anything that came out of an import. Clay puts that ID at the top of the Look up filter list for the same reason: it is the only precise match on offer. |
| A populated HubSpot property came back blank after a run | Ignore blank values was turned off on the Update action. With it off, a blank Clay cell is sent through and overwrites what HubSpot had. | Turn it back on, and keep the properties your reps maintain out of the write entirely. It is on by default, so this is a setting somebody changed on purpose. |
| A company domain lost its subdomain on the way in | Keep subdomains in Company domain is off by default, so shop.example.com is reduced to example.com before the write lands. | Switch it on in the Create or Update action, and separately in Look up if you are filtering on a subdomain. The two switches do not follow each other. |
| Credits went roughly twice as far as the row count suggested | Duplicate records in HubSpot arrived as separate rows and every provider ran against both. Actions bill on the attempt, so a duplicate costs exactly what a match costs. | Measure the portal's duplicate rate before the first run and filter the import to the records you mean to pay for. This is the most expensive failure on this pair and all of it happens outside Clay. |

## What breaks, from the vendors' own docs

- **Actions are billed on the attempt.** Clay bills per action rather than per result, so a provider that finds nothing still costs you. On a hard segment the effective cost per filled field is the action rate divided by your match rate, and that multiplier is the whole economics of this route.
- **A write is immediately live.** Update actions change the record every user in the portal sees. There is no staging environment. The standard protection is a small test set, "ignore blank values" left on, and an explicit exclusion list for properties reps maintain.
- **Importing the whole portal is the classic mistake.** Pull a filtered slice: contacts missing a title, companies with no employee count, deals in an open stage. Importing everything costs actions on rows that did not need anything and makes the write step far riskier than it needs to be.

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

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

## Filling the record this integration moves

The integration above moves a record between two systems. Neither of them creates what is in it, so a sync that works perfectly still carries whatever gaps the record arrived with. Reverse Contact resolves an email, a domain or a profile URL into a verified people and company record through one API, and returns null with a confidence score rather than a guess.

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

- Clay docs: HubSpot integration overview: https://university.clay.com/docs/hubspot-integration-overview
- Clay: how to enrich HubSpot records: https://www.clay.com/guides/how-to-enrich-hubspot-records
- Clay pricing: the plan comparison: https://www.clay.com/pricing
- HubSpot knowledge base: create custom objects: https://knowledge.hubspot.com/object-settings/create-custom-objects
- 14 practitioner threads read on 2026-10-11, summarised on the page: https://www.reversecontact.com/integrations-hub/hubspot-integrations/hubspot-clay-integration#reddit
- This pair, with the reasoning behind each step: https://www.reversecontact.com/integrations-hub/hubspot-integrations/hubspot-clay-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.*
