gtm-enrichment-smart

# GTM Enrichment — Smart (Multi-Provider Waterfall) ## Setup Read your credentials from ~/.gooseworks/credentials.json: ```bash export GOOSEWORKS_API_KEY=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json'))['api_key'])") export GOOSEWORKS_API_BASE=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json')).get('api_base','https://api.gooseworks.ai'))") ``` If ~/.gooseworks/credentials.json does not exist, tell the user to run: `npx gooseworks login` All endpoints use Bearer auth: `-H "Authorization: Bearer $GOOSEWORKS_API_KEY"` Enrich a lead from an email address (+ optional name) using a waterfall strategy: start with cheap APIs ($0.01 each), cross-reference for confidence, then use expensive AI agents only for gaps. Spends proportionally to lead quality. **Cost**: $0.04 (best) to ~$0.12 (typical with buying signals) to ~$0.26 (worst, Sixtyfour fallback) **Latency**: ~5-15s typical, up to 60s if Sixtyfour fallback triggers ## Input Required: - **email** — the lead's email address (e.g., `jane@acme.com`) Optional: - **name** — full name if known (improves match rate) ## Workflow ### Step 0: Extract Domain + Free Email Check Extract the domain from the email. Check if it's a free email provider. **Free email providers** (skip Brand.dev if match): `gmail.com`, `yahoo.com`, `hotmail.com`, `outlook.com`, `aol.com`, `icloud.com`, `mail.com`, `protonmail.com`, `zoho.com`, `yandex.com`, `gmx.com`, `live.com` Set `is_free_email = true/false` — this gates whether Brand.dev runs in Phase 1. --- ### PHASE 1 — Core (always run, parallel) — ~$0.03-$0.06 Run ALL of these simultaneously: **1a. Apollo People Match** ($0.01): ```bash curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \ -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"api":"apollo","path":"/api/v1/people/match"}' "email": "{email}", "reveal_personal_emails": true }' ``` Extract: `person.name`, `person.title`, `person.linkedin_url`, `person.city`, `person.state`, `person.country`, `person.organization.name`, `person.organization.id` (save org_id for Phase 4), `person.organization.industry`, `person.organization.estimated_num_employees`, `person.organization.keywords`, `person.organization.funding_events`, `person.organization.total_funding`. **1b. Hunter Combined Enrichment** ($0.01): ```bash curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \ -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"api":"hunter","path":"/v2/combined/find","query":{"email":"{email}"}}' ``` Extract: `data.person.first_name`, `data.person.last_name`, `data.person.linkedin_handle`, `data.person.title`, `data.company.name`, `data.company.domain`, `data.company.industry`, `data.company.description`, `data.company.headcount`, `data.company.technologies`, `data.company.twitter`, `data.company.category`. **1c. Brand.dev Retrieve** ($0.03 — CONDITIONAL: only if `is_free_email == false`): ```bash curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \ -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"api":"brand-dev","path":"/v1/brand/retrieve","query":{"domain":"{domain}"}}' ``` Extract: `title` (company name), `description`, `industries` (including `eic` code), `socials` (twitter URL, github URL, linkedin URL), `employeeCount`, `foundedYear`, `location`. **SKIP this call if `is_free_email == true`** — saves $0.03. **1d. Hunter Email Verifier** ($0.01): ```bash curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \ -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"api":"hunter","path":"/v2/email-verifier","query":{"email":"{email}"}}' ``` Extract: `data.status` (valid/invalid/accept_all/webmail/disposable/unknown), `data.result` (deliverable/undeliverable/risky). --- ### PHASE 1 MERGE — Cross-Reference & Confidence After all Phase 1 calls complete, merge data: **Person merge rules:** 1. Full name: prefer Apollo (structured), cross-ref with Hunter 2. Title: prefer Apollo, cross-ref with Hunter 3. LinkedIn URL: prefer Apollo `linkedin_url`, fallback to Hunter `linkedin_handle` (prepend `https://linkedin.com/in/`) 4. Location: prefer Apollo (structured city/state/country) 5. If Apollo and Hunter **agree** on name+title: `confidence = "high"` 6. If only one source has data: `confidence = "medium"` 7. If they **disagree** on name or title: flag conflict, keep both, `confidence = "low"` **Company merge rules:** 1. Name: prefer Apollo org name, cross-ref with Hunter + Brand.dev 2. LinkedIn URL: prefer Brand.dev socials, fallback Apollo 3. Description: prefer Brand.dev (richer), fallback Hunter 4. Employee count: prefer Apollo, cross-ref with Brand.dev + Hunter headcount 5. Funding: use Apollo `funding_events` and `total_funding` 6. Geo: prefer Apollo org location, cross-ref with Brand.dev 7. Tech stack: use Hunter `technologies` 8. Social URLs: use Brand.dev `socials` (twitter, github) **AI/B2B Classification (zero extra cost):** Cross-reference three sources from Phase 1: | Source | AI Signals | B2B Signals | |--------|-----------|-------------| | Brand.dev `description` + `industries.eic` | Parse description for: AI, ML, machine learning, deep learning, neural, LLM, GPT, NLP, computer vision | Parse for: SaaS, B2B, enterprise, platform, API, developer tools, infrastructure | | Apollo `keywords[]` + `industry` | Match keywords against AI terms | Match keywords against B2B terms | | Hunter `category` + company description | Check for AI/ML terms | Check for software/SaaS/B2B terms | Confidence rules: - `high`: 2+ sources agree - `medium`: 1 source has signal - `low`: weak inference only (e.g., "tech company" but no explicit AI/B2B terms) --- ### PHASE 2 — Gap-Fill (conditional) — $0.00-$0.02 **2a. Apollo Organization Enrich** ($0.01 — ONLY if Apollo Phase 1 returned NO `funding_events` or funding data is empty): ```bash curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \ -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"api":"apollo","path":"/api/v1/organizations/enrich","query":{"domain":"{domain}"}}' ``` Extract: `organization.funding_events[]`, `organization.total_funding`, `organization.latest_funding_stage`, `organization.latest_funding_amount`, `organization.estimated_num_employees`, `organization.annual_revenue`. **2b. Tomba Enrich** ($0.01 — ONLY if Apollo and Hunter **disagree** on person name OR title): ```bash curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \ -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"api":"tomba","path":"/v1/enrich","query":{"email":"{email}"}}' ``` Use as tie-breaker. If Tomba agrees with Apollo: use Apollo data. If Tomba agrees with Hunter: use Hunter data. If all three disagree: keep Apollo as primary, flag conflict. --- ### PHASE 3 — Sixtyfour Fallback (conditional, expensive) — $0.00-$0.20 **3a. Sixtyfour Enrich Lead** ($0.10 — ONLY if person NOT found after Phases 1-2, meaning no name AND no title AND no LinkedIn URL from any source): ```bash curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \ -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"api":"sixtyfour","path":"/enrich-lead"}' "lead_info": { "email": "{email}", "domain": "{domain}" }, "struct": { "full_name": "Full legal name of this person", "title": "Current job title", "linkedin_url": "LinkedIn profile URL (full URL)", "city": "City", "state": "State or region", "country": "Country" } }' ``` **3b. Sixtyfour Enrich Company** ($0.10 — ONLY if company has major gaps AND org has >500 employees): Major gaps = missing 2+ of: LinkedIn URL, description, employee count, funding data. ```bash curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \ -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"api":"sixtyfour","path":"/enrich-company"}' "target_company": { "domain": "{domain}" }, "struct": { "company_name": "Official company name", "description": "One-paragraph description", "linkedin_url": "LinkedIn company page URL", "employee_count": "Number of employees", "total_funding_usd": "Total funding raised in USD", "latest_funding_date": "Most recent funding round date", "latest_funding_stage": "Most recent round stage", "latest_funding_amount_usd": "Most recent round amount" } }' ``` --- ### PHASE 4 — Buying Signals (qualified leads only) — $0.00-$0.04 **Gate**: Only run Phase 4 if the company is: - Funded (total_funding > 0) AND - Classified as B2B (is_b2b_saas = true) AND - Has >50 employees **4a. Brand.dev AI Products** ($0.03 — extracts products, pricing tiers, and features from the website): ```bash curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \ -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"api":"brand-dev","path":"/v1/brand/ai/products"}' "domain": "{domain}" }' ``` From the products response, extract buying signals: - **has_enterprise_plan**: Check if any product has "enterprise" in name, tier, or target_audience - **has_self_serve**: Check if any product has a listed price (self-serve) vs "Contact sales" pricing - **target_market**: Infer from `target_audience` arrays across products **4b. Apollo Job Postings** ($0.01 — ONLY if `organization_id` was captured from Phase 1): ```bash curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \ -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"api":"apollo","path":"/api/v1/organizations/{organization_id}/job_postings","query":{"organization_id":"{organization_id}"}}' ```