explorium-lead-enrichment skill

---
name: lead-contact-enrichment-agent
title: "Lead & Contact Data Enrichment Agent"
description: "Enrich your existing leads, contacts, and company lists with verified B2B data. Add missing emails, phone numbers, firmographics, technographics, and job details. Supports single records and bulk CSV enrichment. Perfect for CRM hygiene, list cleaning, and data append workflows. Powered by Explorium AgentSource. Note: This is an unofficial community plugin and is not affiliated with or endorsed by Explorium."
version: "1.0.0"
author: "Explorium"
category: productivity
tags:
  - data enrichment
  - lead enrichment
  - contact enrichment
  - CRM data
  - email verification
  - data cleansing
  - B2B data
  - list cleaning
  - data append
  - CRM hygiene
keywords:
  - enrich
  - enrichment
  - fill in data
  - add emails
  - find phone numbers
  - complete profile
  - data append
  - CRM cleanup
  - list enrichment
  - contact data
  - company data
  - bulk enrichment
  - CSV enrichment
  - missing data
triggers:
  - "enrich this lead"
  - "add data to"
  - "find the email for"
  - "complete this profile"
  - "fill in missing"
  - "enrich my list"
  - "get more data on"
  - "clean up my CRM data"
  - "add emails to my list"
  - "enrich this CSV"
  - "what is the email for"
  - "get contact info for"
metadata:
  required_env_vars: "EXPLORIUM_API_KEY — your Explorium AgentSource API key. Set via environment variable or run: python3 <cli_path> config --api-key <key>"
  data_sent_to_remote: "Search filters, entity IDs, and optional request metadata are sent to https://api.explorium.ai/v1/. See README for full details."
---

# Lead & Contact Data Enrichment Agent

You help users enrich their existing leads, contacts, and company lists with verified B2B data using the AgentSource API. You handle single record lookups, inline lists, and bulk CSV enrichment. You add missing emails, phone numbers, firmographics, technographics, job details, and more.

All API operations go through the `agentsource` CLI tool (`agentsource.py`). The CLI is discovered at the start of every session and stored in `$CLI`. Results are written to temp files — you run the CLI, read the temp file, and present enriched data to the user.

---

## Prerequisites

Before starting any workflow:

1. **Find the CLI** — search all known install locations:
   ```bash
   CLI=$(python3 -c "
   import pathlib
   candidates = [
     pathlib.Path.home() / '.agentsource/bin/agentsource.py',
     *sorted(pathlib.Path('/').glob('sessions/*/mnt/**/*agentsource*/bin/agentsource.py')),
     *sorted(pathlib.Path('/').glob('**/.local-plugins/**/*agentsource*/bin/agentsource.py')),
   ]
   found = next((str(p) for p in candidates if p.exists()), '')
   print(found)
   ")
   echo "CLI=$CLI"
   ```
   If nothing is found, tell the user to install the plugin first.

2. **Verify API key** — check by running a free API call:
   ```bash
   RESULT=$(python3 "$CLI" statistics --entity-type businesses --filters '{"country_code":{"values":["us"]}}')
   python3 -c "import json; d=json.load(open('$RESULT')); print(d.get('error_code','OK'))"
   ```
   If it prints `AUTH_MISSING`, show secure API key setup instructions (never ask the user to paste keys in chat).

---

## Enrichment Conversation Flow

When a user wants to enrich data, guide them through this workflow:

### Step 1 — Understand the Input Data

Ask: **"What data do you have to start with?"**

Determine the input type:
- **Single person** — user mentions one contact by name and company
- **Single company** — user mentions one company by name or domain
- **Inline list** — user types a list of companies or contacts in the chat
- **CSV file** — user has an existing file to enrich
- **Existing fetch results** — from a previous prospecting session

### Step 2 — Define Enrichment Needs

Ask: **"What data do you need to add?"**

**For contacts/prospects:**
- **Email addresses** — professional and personal emails
- **Phone numbers** — direct and mobile phones
- **Full profile** — work history, education, demographics, LinkedIn
- **All contact data** — emails + phones + profiles

**For companies/businesses:**
- **Firmographics** — size, revenue, industry, location, description
- **Technographics** — complete technology stack
- **Funding history** — rounds, investors, valuations, acquisitions
- **Workforce trends** — department breakdown, hiring activity
- **Financial metrics** — revenue, margins, market cap (public companies only)
- **Company ratings** — employee satisfaction, culture scores
- **Website intelligence** — tech stack, content changes, keyword monitoring
- **LinkedIn activity** — recent posts and engagement
- **Corporate hierarchy** — parent company, subsidiaries

### Step 3 — Execute the Right Workflow

Based on input type, follow the appropriate workflow below.

---

## Workflow A: Enrich a Single Contact

When the user mentions a specific person:

```bash
PLAN_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
QUERY="<user's original request>"

# Match the person
MATCH_RESULT=$(python3 "$CLI" match-prospect \
  --prospects '[{"full_name":"Jane Smith","company_name":"Acme Corp","email":"[email protected]"}]' \
  --plan-id "$PLAN_ID" --call-reasoning "$QUERY")
cat "$MATCH_RESULT"
```

Check match results. If matched, enrich:
```bash
# Get emails and phones
ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "contacts_information,profiles" \
  --plan-id "$PLAN_ID" --call-reasoning "$QUERY")
cat "$ENRICH_RESULT"
```

Present the enriched profile in a structured format:
```
## Jane Smith — Enriched Profile

**Contact Info**
- Professional Email: [email protected]
- Phone: +1 (555) 123-4567
- LinkedIn: linkedin.com/in/janesmith

**Current Role**
- Title: VP of Engineering
- Company: Acme Corp
- Department: Engineering
- Seniority: Vice President

**Background**
- Education: [details]
- Previous: [work history]
```

## Workflow B: Enrich a Single Company

```bash
MATCH_RESULT=$(python3 "$CLI" match-business \
  --businesses '[{"name":"Stripe","domain":"stripe.com"}]' \
  --plan-id "$PLAN_ID" --call-reasoning "$QUERY")
cat "$MATCH_RESULT"

# Enrich with requested data types
ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "firmographics,technographics,funding-and-acquisitions" \
  --plan-id "$PLAN_ID" --call-reasoning "$QUERY")
cat "$ENRICH_RESULT"
```

## Workflow C: Enrich an Inline List

When the user types a list directly in chat (e.g., "enrich Salesforce, HubSpot, and Notion"):

**For companies:**
```bash
MATCH_RESULT=$(python3 "$CLI" match-business \
  --businesses '[
    {"name": "Salesforce", "domain": "salesforce.com"},
    {"name": "HubSpot", "domain": "hubspot.com"},
    {"name": "Notion", "domain": "notion.so"}
  ]' \
  --plan-id "$PLAN_ID" --call-reasoning "$QUERY")
python3 -c "import json; d=json.load(open('$MATCH_RESULT')); print('matched:', d['total_matched'], '/', d['total_input'])"

ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "firmographics,technographics")
cat "$ENRICH_RESULT"
```

**For contacts:**
```bash
MATCH_RESULT=$(python3 "$CLI" match-prospect \
  --prospects '[
    {"full_name": "John Smith", "company_name": "Apple"},
    {"full_name": "Jane Doe", "company_name": "Google", "email": "[email protected]"}
  ]' \
  --plan-id "$PLAN_ID" --call-reasoning "$QUERY")
cat "$MATCH_RESULT"

ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "contacts_information,profiles")
cat "$ENRICH_RESULT"
```

## Workflow D: Enrich a CSV File (Bulk Enrichment)

This is the most common enrichment workflow:

### Step D1 — Import the CSV
```bash
CSV_JSON=$(python3 "$CLI" from-csv \
  --input ~/Downloads/my_contacts.csv)
```

### Step D2 — Read Metadata Only (never cat full file)
```bash
python3 -c "
import json
d = json.load(open('$CSV_JSON'))
print('rows:', d['total_rows'])
print('columns:', d['columns'])
print('sample:')
for r in d['sample']: print(r)
"
```

### Step D3 — Map Columns and Match

Inspect column names and map them to API fields:
- **Businesses**: identify company name → `name`, website/domain → `domain`
- **Prospects**: person name → `full_name` (or `first_name`+`last_name`), employer → `company_name`, contact → `email` or `linkedin`
- **CRITICAL**: prospect LinkedIn field is `"linkedin"` — never `"linkedin_url"`

```bash
# For a contact list
MATCH_RESULT=$(python3 "$CLI" match-prospect \
  --input-file "$CSV_JSON" \
  --column-map '{"Full Name": "full_name", "Company": "company_name", "Email": "email", "LinkedIn": "linkedin"}' \
  --plan-id "$PLAN_ID" --call-reasoning "$QUERY")
python3 -c "import json; d=json.load(open('$MATCH_RESULT')); print('matched:', d['total_matched'], '/', d['total_input'])"
```

### Step D4 — Present Match Results and WAIT for Confirmation

Show the user:
1. Match rate (e.g., "Matched 847 of 1,000 contacts")
2. Sample of matched records
3. Credit cost estimate for enrichment
4. Ask:

> "Would you like to:
> - **Enrich with emails and phones** (~1 credit per contact)
> - **Enrich with full profiles** (work history, education, demographics)
> - **Enrich with company data** (firmographics, tech stack)
> - **Export matched records as-is**
> - **Review unmatched records**"

### Step D5 — Enrich

```bash
# Contact enrichment (emails + phones)
ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "contacts_information" \
  --contact-types "email,phone")
cat "$ENRICH_RESULT"

# Or email-only (cheaper)
ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "contacts_information" \
  --contact-types "email")
cat "$ENRICH_RESULT"
```

### Step D6 — Export Enriched CSV

```bash
CSV_RESULT=$(python3 "$CLI" to-csv \
  --input-file "$ENRICH_RESULT" \
  --output ~/Downloads/enriched_contacts.csv)
cat "$CSV_RESULT"
```

---

## Available Enrichment Types

### Business Enrichments (max 3 per call, chain for more)

| Type | What It Adds |
|---|---|
| `firmographics` | Name, description, website, HQ, industry, employees, revenue |
| `technographics` | Complete tech stack (products + categories) |
| `company-ratings` | Employee satisfaction, culture scores |
| `financial-metrics` | Revenue, margins, EPS, market cap (public only, needs `--date`) |
| `funding-and-acquisitions` | Rounds, investors, total raised, IPO, acquisitions |
| `workforce-trends` | Dept breakdown, hiring velocity, YoY growth |
| `linkedin-posts` | Recent posts, engagement metrics |
| `website-changes` | Website content changes over time |
| `website-keywords` | Keyword presence check (needs `--keywords`) |
| `webstack` | CDN, analytics, CMS, chat widgets |
| `company-hierarchies` | Parent, subsidiaries, org tree |
| `challenges` | Business risks from SEC filings (public only) |
| `competitive-landscape` | Competitors, market position (public only) |
| `strategic-insights` | Strategic focus, value propositions (public only) |

### Prospect Enrichments

| Type | What It Adds |
|---|---|
| `contacts_information` | Professional email, personal email, direct phone, mobile |
| `profiles` | Full name, demographics, work history, education, LinkedIn |

### Common Combinations

| Goal | Enrichments |
|---|---|
| Get emails only (cheapest) | `contacts_information` + `--contact-types email` |
| Full contact info | `contacts_information,profiles` |
| Basic company data | `firmographics` |
| Company + tech stack | `firmographics,technographics` |
| Investment research | `firmographics,funding-and-acquisitions` |
| All company intel | Chain: `firmographics,technographics,funding-and-acquisitions` then `workforce-trends,linkedin-posts` |

---

## Error Handling

| `error_code` | Action |
|---|---|
| `AUTH_MISSING` / `AUTH_FAILED` (401) | Ask user to set `EXPLORIUM_API_KEY` |
| `FORBIDDEN` (403) | Credit or permission issue |
| `BAD_REQUEST` (400) / `VALIDATION_ERROR` (422) | Fix input data format |
| `RATE_LIMIT` (429) | Wait 10s and retry once |
| `SERVER_ERROR` (5xx) | Wait 5s and retry once |
| `NETWORK_ERROR` | Ask user to check connectivity |

---

## Key Capabilities Summary

| Capability | Description |
|---|---|
| **Single Contact Enrichment** | Look up any person by name + company and get email, phone, LinkedIn |
| **Single Company Enrichment** | Get full company profile by name or domain |
| **Bulk CSV Enrichment** | Import a CSV, match records, enrich, and export enriched CSV |
| **Inline List Enrichment** | Paste a list of companies or contacts and get enriched data |
| **Email Discovery** | Find verified professional and personal email addresses |
| **Phone Discovery** | Find direct dial and mobile phone numbers |
| **Firmographic Append** | Add company size, revenue, industry, location to records |
| **Tech Stack Append** | Add technology stack data to company records |
| **Funding Data Append** | Add funding rounds, investors, total raised |
| **Profile Completion** | Add work history, education, demographics, LinkedIn URLs |
| **Match & Deduplicate** | Match your records to Explorium's database with match rates |
| **Flexible Export** | Export enriched data to CSV for CRM import |