Lead Enrichment

Lead Enrichment

Use this skill when: user asks to "enrich leads", "find decision makers", "get contacts for companies", "find emails", or any request to turn a company list into actionable contacts.

Overview

This skill takes a list of companies and finds key decision makers with:

• Full name
• Job title
• Work email (verified)
• LinkedIn URL

Uses a 3-stage pipeline:

1. Parallel API - Primary contact discovery
2. Apollo API - Email enrichment fallback
3. MillionVerifier - Email verification

Pre-flight Checks

Required API Keys

Before running enrichment, verify these keys exist:

If keys are missing:

1. Ask user which keys they have
2. Guide them to sign up for missing services
3. Explain what each service does and approximate cost
4. Have them add keys to .env file

Required Input

• Company list: CSV or JSON with at minimum:
  • Company name
  • Website (for domain extraction)
• Optional: ICP segment, priority score, target titles

Stage 1: Contact Discovery (Parallel API)

Purpose

Find 5-10 decision makers per company from public sources.

Process

1. For each company, call Parallel Task API with:

   • Company name
   • Website domain
   • Target titles to find

2. Extract from results:

   • Person name
   • Title
   • Email (if public)
   • LinkedIn URL

Target Titles (customize per ICP)

Executive level:

• Founder, CEO, President, Owner
• CTO, CIO, COO, CFO

VP level:

• VP Supply Chain, VP Procurement, VP Sourcing
• VP Operations, VP Product, VP Engineering

Director level:

• Director Supply Chain, Director Procurement
• Director Operations, Director Product

Manager level:

• Product Manager, Procurement Manager
• Merchandise Manager, Buyer

Parallel API Call

from parallel_web import Parallel

client = Parallel(api_key=os.getenv("PARALLEL_API_KEY"))

result = client.task.create(
    prompt=f"""Find up to 5 key decision makers at {company_name}.
    Website: {website}

    For each person, extract:
    - Full name
    - Job title
    - Work email (if available)
    - LinkedIn URL

    Target titles: {target_titles}
    """,
    processor="base"  # or "core", "pro"
)

Output

{
  "company": "Example Corp",
  "contacts": [
    {
      "name": "John Smith",
      "title": "VP Supply Chain",
      "email": "john.smith@example.com",
      "linkedin": "linkedin.com/in/johnsmith"
    }
  ]
}

Stage 2: Email Enrichment (Apollo API)

Purpose

Find emails for contacts that Parallel didn't return emails for.

Process

1. Filter contacts where email is null/empty

2. For each contact, call Apollo People Match:

   • First name
   • Last name
   • Company domain (extracted from website)

3. Apollo returns:

   • Work email
   • LinkedIn URL (backup)
   • Verified title

Apollo API Call

import requests

def apollo_enrich(first_name, last_name, domain):
    url = "https://api.apollo.io/v1/people/match"
    headers = {
        "Content-Type": "application/json",
        "Cache-Control": "no-cache",
        "X-Api-Key": os.getenv("APOLLO_API_KEY")
    }
    data = {
        "first_name": first_name,
        "last_name": last_name,
        "domain": domain
    }
    response = requests.post(url, headers=headers, json=data)
    return response.json()

Rate Limits

• 0.5 sec between requests (be gentle)
• 60 sec wait on 429 errors
• Bulk endpoint available for up to 10 at once

Stage 3: Email Verification (MillionVerifier)

Purpose

Verify all discovered emails before outreach.

Process

1. Collect all emails (from Parallel + Apollo)
2. Verify each with MillionVerifier API
3. Score quality: good, bad, risky, unknown

MillionVerifier API Call

import requests

def verify_email(email):
    url = f"https://api.millionverifier.com/api/v3/?api={api_key}&email={email}"
    response = requests.get(url)
    return response.json()

Response Fields

Quality Interpretation

Flag Role Addresses

Role addresses (info@, sales@, support@) have lower response rates. Flag them:

• Still usable but deprioritize
• Look for personal emails instead
• Note in output for campaign decisions

Progress Tracking

Resume Capability

Store progress in JSONL files for resumability:

leads/progress/
  parallel.jsonl    - Company + contacts + status
  apollo.jsonl      - Contact + email + status
  millionverifier.jsonl - Email + quality + status

JSONL Format

{"company": "Example Corp", "status": "done", "contacts": [...]}
{"company": "Another Inc", "status": "done", "contacts": [...]}

Resume Logic

Before processing:

1. Load existing progress file
2. Build set of already-processed items
3. Skip items in the set
4. Append new results to progress file

Output Format

Final CSV

company,segment,website,person1_name,person1_title,person1_email,person1_linkedin,person2_name,person2_title,person2_email,person2_linkedin,...

Up to 5 contacts per company (person1 through person5).

Final JSON

{
  "company": "Example Corp",
  "segment": "Tier1_Gloves",
  "website": "example.com",
  "contacts": [
    {
      "name": "John Smith",
      "title": "VP Supply Chain",
      "email": "john.smith@example.com",
      "email_quality": "good",
      "linkedin": "linkedin.com/in/johnsmith"
    }
  ]
}

Execution Flow

Option A: Use Existing Scripts

If pga-2026/scripts/enrichment/ exists with:

• enrich_contacts_parallel.py
• enrich_emails_apollo.py
• verify_emails_millionverifier.py

Run them in sequence:

uv run pga-2026/scripts/enrichment/enrich_contacts_parallel.py
uv run pga-2026/scripts/enrichment/enrich_emails_apollo.py
uv run pga-2026/scripts/enrichment/verify_emails_millionverifier.py

Option B: Manual Enrichment

For small lists (under 10 companies):

1. Use Parallel MCP tool directly for contact discovery
2. Use Apollo API calls for missing emails
3. Use MillionVerifier for verification

Option C: Create New Scripts

For new campaigns without existing scripts:

1. Create script directory: [campaign]/scripts/enrichment/
2. Create 3 stage scripts based on templates
3. Create progress tracking directory
4. Run pipeline

Error Handling

API Failures

Missing Data

Quality Checklist

Before delivering enriched list:

• All companies processed (check progress files)
• Emails verified (good/risky/bad flagged)
• Role addresses flagged (info@, sales@)
• LinkedIn URLs present for contacts
• Output format matches user request (CSV or JSON)
• No duplicate contacts across companies

Cost Awareness

Approximate costs (check current pricing):

For 100 companies with 5 contacts each:

• Parallel: 100 tasks
• Apollo: ~200 email lookups (assuming 40% need enrichment)
• MillionVerifier: ~500 verifications

This skill is generic - works for any campaign, not just Performance Leather.