| name | waterfall-enrich-contacts |
| description | Enrich HubSpot contacts (email, phone, job title) through an external enrichment provider and write results back safely. Pluggable provider adapters with FullEnrich waterfall enrichment as the default; Apollo, Hunter, and Dropcontact included; bring your own via a template. |
| license | MIT |
| metadata | {"author":"tomgranot","version":"1.1","category":"data-enrichment"} |
Waterfall-Enrich Contacts with External Providers
Fill missing emails, phone numbers, and job titles on HubSpot contacts using an external enrichment provider, then write results back with a full audit trail. The provider layer is pluggable: FullEnrich (a waterfall aggregator that queries 20+ upstream sources until one hits) is the default, with Apollo, Hunter, and Dropcontact adapters included and a template for whatever provider your team already pays for.
Why This Matters
The internal enrichment skills (/enrich-company-name, /enrich-industry, /backfill-geo-data) only move data the portal already has. When a contact's email, direct dial, or title simply isn't anywhere in HubSpot, external enrichment is the only fix — and it costs real money per lookup, which is why this skill is built around cost caps, previews, and typed confirmations.
Provider Landscape
| Provider | Adapter | Strength | Model |
|---|
| FullEnrich (default) | providers/fullenrich.py | Waterfall across 20+ sources — best hit rates for email + mobile | Credits per lookup, async bulk API |
| Apollo | providers/apollo.py | Large B2B database, titles + firmographics | Credits; personal-data reveals plan-gated |
| Hunter | providers/hunter.py | Email finding by name+domain, confidence scores | Requests per plan; email only |
| Dropcontact | providers/dropcontact.py | GDPR-first, algorithmic (no stored database) | Credits, async |
| Your provider | copy providers/_template.py | Whatever you already use | — |
| Mock (testing only) | providers/mock.py | Deterministic fake data for /sandbox-self-test and dry runs — no network | Free; never use on production |
| HubSpot Breeze Intelligence | (native, no adapter) | In-platform enrichment + form shortening | Credit add-on; programmatic API access is enterprise-gated — which is exactly why this skill defaults to provider-agnostic adapters |
Switch providers with one env var: ENRICHMENT_PROVIDER=apollo.
Prerequisites
- A HubSpot private app access token (
HUBSPOT_ACCESS_TOKEN in .env) with contact read/write scopes
- Python 3.10+ with
uv
- An account + API key with your chosen provider (e.g.
FULLENRICH_API_KEY from FullEnrich dashboard > Settings > API)
- A compliance check: enrichment sends contact names and company data to a third party and imports personal data (emails, phones). Confirm this fits your data processing agreements and the applicable privacy rules (GDPR/CCPA) before running.
Scripts
| Stage | Script | Run with |
|---|
| Before | scripts/before.py | uv run skills/waterfall-enrich-contacts/scripts/before.py |
| Execute | scripts/execute.py | uv run skills/waterfall-enrich-contacts/scripts/execute.py |
| After | scripts/after.py | uv run skills/waterfall-enrich-contacts/scripts/after.py |
Provider adapters live in scripts/providers/ — one module per provider implementing enrich(contacts) -> results (see _template.py for the contract).
Configuration
Everything is set in .env:
HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx
ENRICHMENT_PROVIDER=fullenrich # fullenrich | apollo | hunter | dropcontact | mock | yours
FULLENRICH_API_KEY=... # the chosen provider's key
ENRICHMENT_TARGET_FIELD=phone # phone | email | jobtitle
ENRICHMENT_MAX_CONTACTS=100 # hard cap per run — credits cost money
ENRICHMENT_OVERWRITE=false # never overwrite existing values (default)
ENRICHMENT_CREDITS_PER_CONTACT=1 # for before.py's cost preview
Execution Pattern
Stage 1: Plan
- Choose the provider and the target field (a phone backfill and an email backfill are separate runs).
- Confirm the compliance check above with whoever owns data privacy.
- Confirm budget:
MAX_CONTACTS × credits-per-lookup is the per-run ceiling. Start with a small run (25-50) and inspect quality before scaling.
Stage 2: Before
uv run skills/waterfall-enrich-contacts/scripts/before.py
Counts candidates (contacts with first name + last name + company but missing the target field) and prints a cost ceiling. Read-only.
Stage 3: Execute
uv run skills/waterfall-enrich-contacts/scripts/execute.py
The script:
- Selects up to
MAX_CONTACTS candidates via the Search API
- Asks for typed confirmation (
ENRICH) before spending credits
- Calls the provider adapter (async providers poll until done)
- Computes writes — existing non-empty HubSpot values are never overwritten unless
ENRICHMENT_OVERWRITE=true; skipped values are still recorded in the audit CSV
- Asks for a second typed confirmation (
WRITE) before touching HubSpot
- Batch-updates contacts and writes the audit CSV (old value, new value, action, source per field)
Stage 4: After
uv run skills/waterfall-enrich-contacts/scripts/after.py
Compares candidate counts against the baseline, then spot-check 10-20 enriched contacts by hand — provider quality varies by segment, and the audit CSV tells you exactly what was written where.
Safety Mechanisms
| Mechanism | Detail |
|---|
| Per-run cap | MAX_CONTACTS (default 100) bounds credit spend per run. Deliberately low — raise it only after verifying quality. |
| No-overwrite default | Existing non-empty values are never replaced unless ENRICHMENT_OVERWRITE=true. Enrichment fills gaps; it does not correct data. |
| Double confirmation | Typed ENRICH before credits are spent; typed WRITE before HubSpot is touched. Aborting between the two costs credits but changes nothing. |
| CSV audit trail | Every field written (and every skip) recorded with old value, new value, and provider source. |
| Rollback data | The audit CSV's old column is the rollback: batch-update those values back to undo a run. |
Rollback
- The execute audit CSV records the previous value of every field it wrote. To undo, batch-update those contact/field pairs back to the
old values (empty string clears a field).
- Values are also individually recoverable from each contact's property history.
Technical Gotchas
- Verify adapter payloads against current provider docs. Provider APIs move fast; each adapter's docstring links the docs and flags what to check. The adapters fail loudly (clear
SystemExit messages) on auth or credit errors before touching HubSpot.
- Waterfall providers are asynchronous. FullEnrich and Dropcontact return results in seconds-to-minutes; the adapters poll. Don't kill the script mid-poll — credits are consumed at submission.
- Enriched emails are unverified senders' risk. A found email is not consent to market. New emails enter as non-marketing data points; your normal opt-in and deliverability rules apply before any sends.
- Match rates of 40-70% are normal. Providers can't find everyone. The audit CSV separates "provider found nothing" (absent) from "found but skipped" (existing value).
- Domain quality drives hit rates. Candidates whose email domain or company website is missing enrich poorly. Run
/enrich-company-name first — better identity inputs, better waterfall results.
- Internal-data-first. If the value exists anywhere in the portal (associated company,
ip_country, form submissions), the free internal skills should fill it — save credits for data HubSpot genuinely doesn't have.
