lead-contact-enrichment-agent

Original source / Raw SKILL.md

---
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 |


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Lead & Contact Data Enrichment Agent

Enrich your existing leads, contacts, and company lists with verified B2B data using the AgentSource API. Add missing emails, phone numbers, firmographics, technographics, and job details. Supports single records and bulk CSV enrichment.

Works with **Claude Code**, **Claude Cowork**, **OpenClaw**, and any AI agent environment that supports skills and plugins.

## How It Works

1. Provide your data — a single contact, a list, or a CSV file
2. Tell the agent what data you need (emails, phones, company info, etc.)
3. The agent matches your records, enriches them, and shows a preview
4. You confirm — then it exports the enriched data to CSV

## Requirements

- Python 3.8+ (standard library only)
- An Explorium AgentSource API key
- Any AI agent environment that supports skills/plugins

## Quick Start

### 1. Install
```bash
./setup.sh
```

### 2. Set your API key

**Do not share your API key in the AI chat.** Set it securely:

```bash
export EXPLORIUM_API_KEY=your_api_key_here
# Or: python3 ~/.agentsource/bin/agentsource.py config --api-key your_api_key_here
```

### 3. Start enriching
```
Find the email for Jane Smith at Stripe
```
```
Enrich Salesforce, HubSpot, and Notion with firmographics and tech stack
```
```
Enrich my CSV at ~/Downloads/contacts.csv with emails and phone numbers
```
```
Add company data to my lead list at ~/Downloads/leads.csv
```
```
Get contact info for John Doe at Apple and Sarah Chen at Google
```

## Key Features

- **Single Contact Enrichment** — Look up any person by name + company
- **Bulk CSV Enrichment** — Import, match, enrich, and re-export CSVs
- **Inline List Support** — Paste a list of companies or contacts directly
- **Email Discovery** — Verified professional and personal emails
- **Phone Discovery** — Direct dial and mobile numbers
- **Firmographic Append** — Company size, revenue, industry, location
- **Tech Stack Append** — Full technology stack data
- **Funding Data** — Rounds, investors, total raised
- **Profile Completion** — Work history, education, LinkedIn URLs
- **Match & Deduplicate** — Match rates show data quality

## Data & Privacy

All API calls go to `https://api.explorium.ai/v1/`. See SKILL.md for full data handling details.

```

### _meta.json

```json
{
  "owner": "haroexplorium",
  "slug": "explorium-lead-enrichment",
  "displayName": "lead-contact-enrichment-agent",
  "latest": {
    "version": "1.0.0",
    "publishedAt": 1772264433823,
    "commit": "https://github.com/openclaw/skills/commit/0818f876c4e3b09653e80c2274c15535eb178a7f"
  },
  "history": []
}

```

### references/enrichments.md

```markdown
# Enrichment Reference

Enrichments add detailed data fields to fetch results and consume additional credits.
**Max 3 enrichment types per single enrich call.** Chain multiple calls for more.

## Business Enrichments (`enrich-business` command)

| Enrichment Type | Data Provided | Notes |
|---|---|---|
| `enrich-business-firmographics` | Name, description, website, HQ location, industry, employee count, revenue range | Basic company profile — usually the first enrichment |
| `enrich-business-technographics` | Complete tech stack (products + categories) | Identifies what software the company uses |
| `enrich-business-company-ratings` | Employee satisfaction, culture scores, Glassdoor-style ratings | |
| `enrich-business-financial-metrics` | Revenue, margins, EPS, EBITDA, market cap | **Public companies only**. Requires `--date YYYY-MM-DD` (the reporting period) |
| `enrich-business-funding-and-acquisitions` | Funding rounds, investors, total raised, IPO details, acquisitions | Includes round type (Seed/Series A-E/PE/etc.) |
| `enrich-business-challenges` | Business risks, strategic challenges from SEC 10-K filings | **Public companies only** |
| `enrich-business-competitive-landscape` | Competitors, market positioning from SEC filings | **Public companies only** |
| `enrich-business-strategic-insights` | Strategic focus, value propositions, key initiatives from SEC filings | **Public companies only** |
| `enrich-business-workforce-trends` | Dept headcount breakdown, hiring velocity, YoY growth by department | |
| `enrich-business-linkedin-posts` | Recent company LinkedIn posts, engagement metrics (likes, comments, shares) | |
| `enrich-business-website-changes` | Website content changes detected over time, summary of updates | |
| `enrich-business-website-keywords` | Whether specific keywords appear on company website | Requires `--keywords kw1,kw2` |
| `enrich-business-webstack` | Web-specific tech: CDN, analytics platforms, CMS, chat widgets | More granular than technographics for web layer |
| `enrich-business-company-hierarchies` | Parent company, subsidiaries, org tree structure | Output is nested JSON |

## Prospect Enrichments (`enrich-prospects` command)

| Enrichment Type | Data Provided | Notes |
|---|---|---|
| `enrich-prospects-contacts` | Professional email, personal email, direct phone, mobile phone | Use `--contact-types email,phone` to limit scope; `email` only is cheaper |
| `enrich-prospects-profiles` | Full name, demographics, current & past work history, education, LinkedIn URL | |

## Common Enrichment Combinations

| Use Case | Enrichments |
|---|---|
| Basic company profile | `enrich-business-firmographics` |
| Tech stack + company info | `enrich-business-firmographics,enrich-business-technographics` |
| Investor/VC targeting | `enrich-business-firmographics,enrich-business-funding-and-acquisitions` |
| Website intelligence | `enrich-business-website-changes,enrich-business-webstack` |
| Workforce growth signals | `enrich-business-workforce-trends,enrich-business-firmographics` |
| Full contact list | `enrich-prospects-contacts,enrich-prospects-profiles` |
| Email-only list (cheaper) | `enrich-prospects-contacts` + `--contact-types email` |
| All company intel (chain 2 calls) | Call 1: `enrich-business-firmographics,enrich-business-technographics,enrich-business-funding-and-acquisitions` → Call 2: `enrich-business-workforce-trends,enrich-business-linkedin-posts` |

## Critical Rules

1. **Always use `enriched_table_name`** from the enrich response in all subsequent operations (export, further enrich, events). The enriched table is a new table — do not use the original fetch table name.
2. **Chain enrichments sequentially**: Each enrich call returns a new `enriched_table_name`; pass it as `--table-name` to the next enrich call.
3. **Public company enrichments** (`financial-metrics`, `challenges`, `competitive-landscape`, `strategic-insights`) return empty data for private companies — use `is_public_company: true` filter when these are the goal.
4. **Re-present sample** to the user after enrichment before asking about export.

```

### references/events.md

```markdown
# Events Reference

Events let you filter for companies/prospects based on recent real-world triggers, or fetch detailed event data for a result set.

## Business Events (`business-events` command)

### Growth & Expansion
| Event Type | Description |
|---|---|
| `new_funding_round` | New investment round (Seed, Series A/B/C/D/E, PE, etc.) |
| `ipo_announcement` | IPO filed or publicly announced |
| `new_investment` | Company made an investment in another company |
| `new_product` | New product or service launched or announced |
| `new_office` | New office location opened |
| `new_partnership` | New strategic partnership or integration announced |
| `company_award` | Award, recognition, or ranking received |

### Hiring & Workforce Growth
| Event Type | Description |
|---|---|
| `increase_in_engineering_department` | Engineering headcount growing |
| `increase_in_sales_department` | Sales headcount growing |
| `increase_in_marketing_department` | Marketing headcount growing |
| `increase_in_operations_department` | Operations headcount growing |
| `increase_in_customer_service_department` | Customer service headcount growing |
| `increase_in_all_departments` | Company-wide headcount growth |
| `hiring_in_engineering_department` | Active engineering job postings |
| `hiring_in_sales_department` | Active sales job postings |
| `hiring_in_marketing_department` | Active marketing job postings |
| `hiring_in_finance_department` | Active finance job postings |
| `hiring_in_legal_department` | Active legal job postings |
| `hiring_in_operations_department` | Active operations job postings |
| `hiring_in_human_resources_department` | Active HR job postings |
| `hiring_in_creative_department` | Active creative job postings |
| `hiring_in_education_department` | Active education job postings |
| `hiring_in_health_department` | Active healthcare job postings |
| `hiring_in_professional_service_department` | Active professional services job postings |
| `hiring_in_support_department` | Active support job postings |
| `hiring_in_trade_department` | Active trade job postings |
| `hiring_in_unknown_department` | Active hiring, department unclear |
| `employee_joined_company` | Notable senior employee joined the company |

### Contraction & Challenges
| Event Type | Description |
|---|---|
| `decrease_in_engineering_department` | Engineering headcount shrinking |
| `decrease_in_sales_department` | Sales headcount shrinking |
| `decrease_in_marketing_department` | Marketing headcount shrinking |
| `decrease_in_operations_department` | Operations headcount shrinking |
| `decrease_in_customer_service_department` | Customer service headcount shrinking |
| `decrease_in_all_departments` | Company-wide headcount contraction / layoffs |
| `closing_office` | Office location closed |
| `cost_cutting` | Cost reduction initiatives announced |
| `merger_and_acquisitions` | M&A activity (being acquired or acquiring) |
| `lawsuits_and_legal_issues` | Legal proceedings, regulatory actions |
| `outages_and_security_breaches` | Technical incidents, security breaches |

---

## Prospect Events (`prospect-events` command)

| Event Type | Description |
|---|---|
| `prospect_changed_role` | Person promoted or changed roles within the same company |
| `prospect_changed_company` | Person moved to a new company |
| `prospect_job_start_anniversary` | Tenure milestone (1-year, 2-year, etc.) |

---

## Using Events as a Fetch Filter

To filter the search result to only include companies that experienced a specific event, add the `events` filter inside the `--filters` JSON of the `fetch` command:

```json
{
  "events": {
    "values": ["new_funding_round", "hiring_in_engineering_department"],
    "last_occurrence": 60,
    "negate": false
  }
}
```

`last_occurrence`: number of days to look back — **30 to 90 only** (hard API limit). Cannot exceed 90.

---

## Fetching Detailed Event Data

After fetching entities, call `business-events` or `prospect-events` to retrieve the actual event details for each company/prospect in the result table.

```bash
RESULT=$(python ~/.agentsource/bin/agentsource.py business-events \
  --session-id "$SESSION_ID" \
  --table-name "$TABLE_NAME" \
  --event-types "new_funding_round,new_partnership" \
  --since "2025-11-01")
cat "$RESULT"
```

**Sample vs. Export**:
- Sample preview (via `--sample-size 3-5`): Shows up to 3 events per entity
- Full export: ALL events per entity, which can be tens to hundreds per company

**Note**: Event data is returned as a new `events_table_name` — use this table name when calling `export`.

---

## Common Event-Driven Workflows

| Sales Trigger | Events to Use |
|---|---|
| Companies that just raised money | `new_funding_round` |
| Companies actively hiring (expansion signal) | `increase_in_all_departments`, `hiring_in_engineering_department` |
| Companies going through change (potential buyer) | `merger_and_acquisitions`, `new_product`, `new_partnership` |
| Distressed companies (cost-cutting tools) | `cost_cutting`, `decrease_in_all_departments`, `closing_office` |
| New executive hire (champion at new company) | `employee_joined_company` |
| Person who just changed jobs (new budget) | `prospect_changed_company`, `prospect_changed_role` |

```

### references/filters.md

```markdown
# Filter Reference

All filters are passed inside the `--filters` JSON argument of `fetch` and `statistics` commands.

## Filter JSON Structure

Every filter uses this shape:
```json
{
  "filter_name": {
    "values": ["value1", "value2"],
    "negate": false
  }
}
```
Set `"negate": true` to **exclude** entities matching those values.

---

## Filters Requiring Autocomplete (MANDATORY)

These fields MUST be resolved via the `autocomplete` command before use.
Never pass raw user text directly — always use the standardized values returned.

| Filter Field | `--field` Arg | Example Query |
|---|---|---|
| `linkedin_category` | `linkedin_category` | `"software development"`, `"financial services"` |
| `naics_category` | `naics_category` | `"software"`, `"healthcare"` |
| `job_title` | `job_title` | `"Chief Technology Officer"`, `"Account Executive"` |
| `business_intent_topics` | `business_intent_topics` | `"CRM software"`, `"cloud migration"` |
| `company_tech_stack_tech` | `company_tech_stack_tech` | `"Salesforce"`, `"React"`, `"Kubernetes"` |
| `city_region` | `city_region` | `"San Francisco"`, `"New York"` (US cities only) |

**Mutual exclusion**: Never use both `linkedin_category` AND `naics_category` in the same query.

---

## Enum Filters (Use Values Directly — No Autocomplete)

### `company_size` (number of employees)
```
"1-10"  "11-50"  "51-200"  "201-500"  "501-1000"
"1001-5000"  "5001-10000"  "10001+"
```

### `company_revenue` (annual revenue)
```
"0-500K"  "500K-1M"  "1M-5M"  "5M-10M"  "10M-25M"  "25M-75M"
"75M-200M"  "200M-500M"  "500M-1B"  "1B-10B"  "10B-100B"  "100B-1T"
"1T-10T"  "10T+"
```

### `company_age` (years since founding)
```
"0-3"  "3-6"  "6-10"  "10-20"  "20+"
```

### `number_of_locations`
```
"0-1"  "2-5"  "6-20"  "21-50"  "51-100"  "101-1000"  "1001+"
```

### `company_tech_stack_category`
```
"Technology"  "Marketing"  "E-commerce"  "Devops And Development"
"Programming Languages And Frameworks"  "Testing And Qa"
"Platform And Storage"  "Health Tech"  "Business Intelligence And Analytics"
"Operations Management"  "Customer Management"  "Hr"
"Industrial Engineering And Manufacturing"  "Product And Design"
"Sales"  "It Security"  "It Management"  "Finance And Accounting"
"Computer Networks"  "Collaboration"  "Communications"
"Productivity And Operations"  "Healthcare And Life Science"  "Other"
```

### `job_level` (prospects only)
```
"c-suite"  "manager"  "owner"  "senior non-managerial"  "partner"
"freelancer"  "junior"  "director"  "board member"  "founder"
"president"  "senior manager"  "advisor"  "non-managerial"  "vice president"
```

### `job_department` (prospects only)
```
"administration"  "healthcare"  "partnerships"  "c-suite"  "design"
"human resources"  "engineering"  "education"  "strategy"  "product"
"sales"  "r&d"  "retail"  "customer success"  "security"  "public service"
"creative"  "it"  "support"  "marketing"  "trade"  "legal"  "operations"
"real estate"  "procurement"  "data"  "manufacturing"  "logistics"  "finance"
```

---

## Location Filters

### Country codes (ISO Alpha-2)
Use with `company_country_code` or `prospect_country_code`:
```
"US"  "GB"  "DE"  "FR"  "IL"  "CA"  "AU"  "SG"  "IN"  "NL"  ...
```

### Region/State codes (ISO 3166-2)
Use with `company_region_country_code` or `prospect_region_country_code`:
```
"US-CA"  "US-NY"  "US-TX"  "US-FL"  "US-WA"  "IL-TA"  "GB-ENG"  ...
```

**Mutual exclusion**: Never combine `company_country_code` AND `company_region_country_code` (same applies to prospect variants). Use one or the other.

**US cities**: Use `city_region` filter (requires autocomplete) instead of `region_country_code` for city-level targeting.

---

## Boolean / Presence Filters

| Filter | Valid Values | Notes |
|---|---|---|
| `has_website` | `true`, `false`, `null` | null = no filter |
| `is_public_company` | `true`, `false`, `null` | true = NYSE/NASDAQ listed |
| `has_email` | `true`, `null` | prospects only; use `true` when contact emails needed |
| `has_phone_number` | `true`, `null` | prospects only |

---

## Range Filters (Prospects Only)

### `total_experience_months`
```json
{ "total_experience_months": { "gte": 24, "lte": 120 } }
```

### `current_role_months`
```json
{ "current_role_months": { "gte": 6, "lte": 36 } }
```

---

## Event Filter (use within `fetch`)

Filter businesses that have a specific event within a lookback window:
```json
{
  "events": {
    "values": ["new_funding_round", "new_partnership"],
    "last_occurrence": 60,
    "negate": false
  }
}
```
`last_occurrence`: number of days (30–90 only, **cannot exceed 90**).

---

## Title vs. Department/Level

- For **specific titles**: use `job_title` (requires autocomplete)
- For **broad roles**: use `job_level` + `job_department` (no autocomplete)
- **Never** combine `job_title` WITH `job_level` or `job_department` in the same query

---

## Example Filter Objects

### US SaaS companies, 51–500 employees
```json
{
  "linkedin_category": { "values": ["Software Development"] },
  "company_country_code": { "values": ["US"] },
  "company_size": { "values": ["51-200", "201-500"] }
}
```

### CTOs at companies using Salesforce (prospects)
```json
{
  "job_title": { "values": ["Chief Technology Officer"] },
  "company_tech_stack_tech": { "values": ["Salesforce"] }
}
```

### Companies with recent funding in fintech
```json
{
  "linkedin_category": { "values": ["Financial Services"] },
  "events": { "values": ["new_funding_round"], "last_occurrence": 60 }
}
```

### Exclude companies under 10 employees
```json
{
  "company_size": { "values": ["1-10"], "negate": true }
}
```

```