$ man clay-wiki/hubspot-create-update

The HubSpot Create-Lookup-Update pattern is how you sync enriched data from Clay into your CRM without creating duplicates, overwriting good data, or stepping on active deals. It's three operations in sequence: lookup (does this record already exist?), create (if not, make one), update (if so, add new data without destroying old data). This pattern applies to both contact and company objects. Get it wrong and your CRM fills with duplicates. Get it right and Clay becomes the enrichment engine that keeps your CRM current.

PATTERN

Before Clay creates anything in HubSpot, it must check if the record already exists. For contacts, lookup by email. For companies, lookup by domain. Why this is non-negotiable: if you skip the lookup, Clay creates a new contact record even when that person is already in HubSpot with an active deal, 6 months of activity history, and a rep assigned. The sales rep gets confused. The pipeline gets messy. Reporting breaks. And your credibility with the sales team is gone. The CRM lookup is the first column that should fire in any Clay table that syncs downstream. Before enrichment, before qualification, before routing — lookup first. Always.

PATTERN

After lookup, Clay has two paths: Path A — Record NOT found: Create a new contact or company in HubSpot. Map all enriched Clay columns to HubSpot properties. Set lifecycle stage (usually "Lead" for outbound). Associate the contact with the company object. Path B — Record FOUND: Update the existing record. But not blindly. Update rules: • Empty fields in HubSpot → fill from Clay (enrichment value add) • Populated fields in HubSpot → do NOT overwrite unless the Clay data is newer AND more reliable • Protected fields (owner, deal stage, lifecycle stage if advanced) → never overwrite from Clay • Enrichment timestamp → always update so the team knows when data was last refreshed The update logic prevents Clay from stomping on data that humans or other systems have curated. Clay adds. It doesn't replace.

PATTERN

Every Clay column that syncs to HubSpot needs a corresponding custom property. Standard mappings: • Clay ICP score → HubSpot custom property: icp_score (number, 0-10) • Clay persona tier → HubSpot custom property: persona_tier (number, 1-5) • Clay MX provider → HubSpot custom property: mx_provider (text: Google/Microsoft/Other) • Clay enrichment date → HubSpot custom property: last_clay_sync (date) • Clay service fit → HubSpot custom property: service_fit (text) • Clay web reveal date → HubSpot custom property: web_reveal_date (date) • Clay confidence → HubSpot custom property: qualification_confidence (text: High/Medium/Low) Create these properties in HubSpot before you set up the Clay sync. If the property doesn't exist, the sync fails silently and data gets lost.

PATTERN

Deduplication happens at two levels: Level 1 — Clay table level: Before syncing, deduplicate your Clay table by email (contacts) or domain (companies). Use Sculptor for fuzzy matching if needed. One record per person, one record per company. Level 2 — CRM level: The lookup handles most deduplication. But edge cases exist: a contact with two email addresses, a company with multiple domains, a name that appears slightly different. For these, add a secondary lookup — check by name + company if the email lookup returns no match. The goal: zero duplicate creation. Every record Clay touches in HubSpot should either be a clean create (genuinely new) or a clean update (existing record, enriched with fresh data).

PRO TIP

The HubSpot integration pattern isn't just a technical workflow. It's a trust protocol. Every time Clay sends data to HubSpot, a sales team relies on that data to make decisions. If Clay creates duplicates, the rep wastes time. If Clay overwrites deal notes, the rep loses context. If Clay adds contacts to a sequence that are already in active conversations, the rep looks incompetent. Before building any Clay-to-HubSpot sync, ask: what's the worst thing that could happen if this sync runs incorrectly? Then build guardrails to prevent it. Lookup first. Never overwrite protected fields. Never route to outreach without checking pipeline status.

ANTI-PATTERN

Mapping Clay fields to default HubSpot properties that other systems also write to. If your marketing automation also updates lifecycle stage, and Clay also updates lifecycle stage, they'll fight. Create custom properties for Clay-specific data. Let marketing automation own its properties. Let Clay own its properties. No conflicts. Another mistake: syncing every Clay row to HubSpot. Only sync qualified, enriched records. If an account scored 3/10 on ICP fit, it doesn't belong in the CRM. The CRM should only contain records worth a salesperson's attention.