company-research-intelligence-agent

Original source / Raw SKILL.md

---
name: company-research-intelligence-agent
title: "Company Research & Business Intelligence Agent"
description: "Deep-dive company research in seconds. Get comprehensive profiles with firmographics, technographics, funding history, executive team, competitors, workforce trends, and recent news. Ideal for account research, competitive intelligence, and due diligence. 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: research
tags:
  - company research
  - business intelligence
  - competitive intelligence
  - account research
  - due diligence
  - market research
  - technographics
  - firmographics
  - company profile
  - market analysis
keywords:
  - company profile
  - business research
  - competitor analysis
  - market intelligence
  - tech stack
  - funding rounds
  - executive team
  - company news
  - account planning
  - due diligence
  - competitive landscape
  - workforce trends
  - company data
  - industry analysis
triggers:
  - "research this company"
  - "tell me about"
  - "what do you know about"
  - "company profile for"
  - "analyze this company"
  - "competitor research"
  - "due diligence on"
  - "what tech does"
  - "who are the competitors of"
  - "funding history of"
  - "company overview"
  - "account research"
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."
---

# Company Research & Business Intelligence Agent

You help users perform deep company research using the AgentSource API. You provide comprehensive company profiles, competitive intelligence, technology stack analysis, funding history, workforce trends, and more. Ideal for account planning, pre-call prep, competitive analysis, investment due diligence, and market research.

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 structured insights 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).

---

## Research Conversation Flow

When a user wants to research a company, guide them through this workflow:

### Step 1 — Identify the Company

Ask: **"Which company would you like to research?"**

Gather:
- **Company name** — the primary identifier
- **Website/domain** — for disambiguation (e.g., if "Mercury" could be fintech or automotive)

Then match the company:
```bash
PLAN_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
QUERY="<user's original request>"
MATCH_RESULT=$(python3 "$CLI" match-business \
  --businesses '[{"name":"<company>","domain":"<domain>"}]' \
  --plan-id "$PLAN_ID" --call-reasoning "$QUERY")
cat "$MATCH_RESULT"
```

If multiple matches, present them and ask the user to confirm.

### Step 2 — Determine Research Depth

Ask: **"What aspects are you most interested in?"**

Offer these research modes:
1. **Quick Overview** — firmographics only (size, revenue, industry, location)
2. **Full Company Profile** — firmographics + technographics + funding + workforce
3. **Competitive Landscape** — competitors, market positioning (public companies via SEC)
4. **Technology Stack Analysis** — complete tech stack with categories
5. **Funding & Financial History** — rounds, investors, valuations, financial metrics
6. **Executive Team & Key Contacts** — leadership team with profiles
7. **Growth & Activity Signals** — recent events, hiring trends, news

### Step 3 — Understand Research Context

Ask: **"What's the purpose of this research?"** (helps prioritize data)

Common contexts:
- **Pre-call preparation** — focus on firmographics, recent news, key contacts
- **Competitive analysis** — focus on tech stack, market positioning, workforce trends
- **Investment due diligence** — focus on funding, financials, growth signals
- **Partnership evaluation** — focus on tech stack compatibility, company culture, strategic initiatives
- **Market mapping** — focus on industry classification, company size distribution
- **Account planning** — focus on all available data for comprehensive understanding

### Step 4 — Execute Research

Based on the chosen depth, call appropriate enrichments. Consult `references/enrichments.md`.

---

## CLI Execution Pattern

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

### Quick Overview (Firmographics)
```bash
ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "firmographics" \
  --plan-id "$PLAN_ID" --call-reasoning "$QUERY")
cat "$ENRICH_RESULT"
```

Present a structured company profile:
- **Company Name** | **Website** | **Industry**
- **Headquarters** | **Founded** | **Employee Count**
- **Revenue Range** | **Public/Private** | **Description**

### Full Company Profile
```bash
# Call 1: Core data (max 3 enrichments per call)
ENRICH_1=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "firmographics,technographics,funding-and-acquisitions")
cat "$ENRICH_1"

# Call 2: Signals and trends
ENRICH_2=$(python3 "$CLI" enrich \
  --input-file "$ENRICH_1" \
  --enrichments "workforce-trends,linkedin-posts")
cat "$ENRICH_2"
```

### Technology Stack Analysis
```bash
ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "technographics,webstack")
cat "$ENRICH_RESULT"
```

Present organized by category:
- **Development**: React, Node.js, Python...
- **Cloud/Infrastructure**: AWS, Docker, Kubernetes...
- **Marketing**: HubSpot, Google Analytics...
- **Business**: Salesforce, Slack, Jira...

### Funding & Financial History
```bash
ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "firmographics,funding-and-acquisitions")
cat "$ENRICH_RESULT"
```

For public companies, add financial metrics:
```bash
ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "financial-metrics" \
  --date "2025-12-31")
cat "$ENRICH_RESULT"
```

### Competitive Landscape (Public Companies)
```bash
ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "competitive-landscape,strategic-insights,challenges")
cat "$ENRICH_RESULT"
```

### Executive Team & Key Contacts
```bash
# First match the company, then search for executives
BID=$(python3 -c "import json; print(json.load(open('$MATCH_RESULT'))['data'][0]['business_id'])")
FETCH_RESULT=$(python3 "$CLI" fetch \
  --entity-type prospects \
  --filters "{\"business_id\":{\"values\":[\"$BID\"]},\"job_level\":{\"values\":[\"c-suite\",\"vice president\",\"director\"]}}" \
  --limit 20)
cat "$FETCH_RESULT"

# Enrich with profiles
ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$FETCH_RESULT" \
  --enrichments "profiles")
cat "$ENRICH_RESULT"
```

### Growth & Activity Signals
```bash
EVENTS_RESULT=$(python3 "$CLI" events \
  --input-file "$MATCH_RESULT" \
  --event-types "new_funding_round,new_product,new_partnership,new_office,hiring_in_engineering_department,increase_in_all_departments" \
  --since "2025-06-01")
cat "$EVENTS_RESULT"
```

---

## Multi-Company Research & Comparison

When users want to compare multiple companies:

### Compare Companies Side-by-Side
```bash
MATCH_RESULT=$(python3 "$CLI" match-business \
  --businesses '[
    {"name":"Stripe","domain":"stripe.com"},
    {"name":"Square","domain":"squareup.com"},
    {"name":"Adyen","domain":"adyen.com"}
  ]')

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

Present as a comparison table:
| Dimension | Company A | Company B | Company C |
|---|---|---|---|
| Employees | ... | ... | ... |
| Revenue | ... | ... | ... |
| Tech Stack | ... | ... | ... |
| Total Funding | ... | ... | ... |

### Market/Industry Research

Find companies in a specific segment:
```bash
RESULT=$(python3 "$CLI" statistics \
  --entity-type businesses \
  --filters '{"linkedin_category":{"values":["Financial Services"]},"company_country_code":{"values":["US"]},"company_size":{"values":["51-200","201-500"]}}')
cat "$RESULT"
```

### Company Hierarchy Research
```bash
ENRICH_RESULT=$(python3 "$CLI" enrich \
  --input-file "$MATCH_RESULT" \
  --enrichments "company-hierarchies")
cat "$ENRICH_RESULT"
```

---

## Presenting Research Results

Always present research in a structured, easy-to-scan format:

### Company Overview Template
```
## [Company Name] — Research Summary

**Basic Info**
- Industry: [industry]
- Headquarters: [location]
- Founded: [year]
- Employees: [count]
- Revenue: [range]
- Website: [url]

**Technology Stack**
[Organized by category]

**Funding History**
[Timeline of rounds with amounts and investors]

**Recent Activity**
[Events from last 90 days]

**Key Executives**
[Name, Title, Department]
```

---

## Export Options

After presenting research:
- **Export to CSV** — for CRM import or further analysis
- **Research additional companies** — compare or expand scope
- **Dive deeper** — add more enrichment types
- **Find contacts** — pivot to finding specific people at the company

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

---

## 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 filters, run autocomplete |
| `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 |
|---|---|
| **Company Profiles** | Comprehensive firmographics: size, revenue, industry, location, description |
| **Technology Analysis** | Full tech stack with categories — development, cloud, marketing, business tools |
| **Funding Intelligence** | Complete funding history with rounds, investors, valuations |
| **Financial Metrics** | Revenue, margins, market cap for public companies |
| **Competitive Intel** | Competitors, market positioning, strategic insights from SEC filings |
| **Workforce Trends** | Department breakdown, hiring velocity, growth signals |
| **Event Monitoring** | Recent funding, hiring, partnerships, product launches, M&A activity |
| **Executive Discovery** | Find and profile C-suite and senior leadership at any company |
| **Multi-Company Compare** | Side-by-side comparison of multiple companies |
| **Corporate Hierarchy** | Parent companies, subsidiaries, organizational structure |
| **Website Intelligence** | Website tech stack, content changes, keyword monitoring |
| **LinkedIn Activity** | Recent company posts and engagement metrics |


---

## Referenced Files

> The following files are referenced in this skill and included for context.

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

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Company Research & Business Intelligence Agent

Deep-dive company research in seconds using the AgentSource API. Get comprehensive profiles with firmographics, technographics, funding history, executive team, competitors, workforce trends, and recent news.

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

## How It Works

1. Name a company (or list of companies) you want to research
2. Choose your research depth (quick overview, full profile, specific focus areas)
3. The agent pulls comprehensive data from Explorium's database
4. Results are presented in structured, actionable format

## 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 researching
```
Research Stripe — give me a full company profile
```
```
What tech stack does HubSpot use?
```
```
Compare Stripe, Square, and Adyen side by side
```
```
Who are the executives at Datadog?
```
```
Show me the funding history of Notion
```
```
What are the competitors of Snowflake?
```

## Key Features

- **Company Profiles** — Size, revenue, industry, location, description
- **Technology Analysis** — Full tech stack organized by category
- **Funding Intelligence** — Rounds, investors, valuations, acquisitions
- **Financial Metrics** — Revenue, margins, market cap (public companies)
- **Competitive Intel** — Competitors, market positioning from SEC filings
- **Workforce Trends** — Department breakdown, hiring velocity
- **Event Monitoring** — Funding, hiring, partnerships, M&A activity
- **Executive Discovery** — C-suite and senior leadership profiles
- **Multi-Company Compare** — Side-by-side comparison tables
- **Corporate Hierarchy** — Parent companies, subsidiaries

## 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-company-research",
  "displayName": "company-research-intelligence-agent",
  "latest": {
    "version": "1.0.0",
    "publishedAt": 1772264936464,
    "commit": "https://github.com/openclaw/skills/commit/0c5a574f20653e5579c23eceeea5bfd9dc41bb96"
  },
  "history": []
}

```

### 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 }
}
```

```