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 A