List Expander — seed companies → lookalikes → mined filters → qualified TAM
The problem this solves
Niche lists come out tiny because we search databases with narrow explicit keywords, but real good-fit companies (e.g. Atlantic Medical Group, Hackensack Meridian) often don't carry that keyword in their database record. Instead of guessing keywords top-down, this skill works bottom-up: take companies you KNOW fit, discover how the database actually tags them, expand via lookalike engines, and only then derive the wide-net filters — with measured precision per filter — before pulling and AI-qualifying at scale.
Pipeline (5 phases)
All scripts live in scripts/, run with npx tsx, and are dependency-free (node ≥ 18 native
fetch). Every script takes --help. Keys load from the repo-root .env (see .env.example),
falling back to ~/.env. Artifacts land in ~/output/list-expander/{run}/.
Phase 1 fingerprint.ts seeds → how each shows up in Prospeo + its live homepage Phase 2 lookalikes.ts seeds → candidates via Prospeo lookalike + Exa + Parallel (qualify candidates → lookalikes-confirmed.csv) Phase 3 mine-filters.ts confirmed fits → candidate filters → scorecard (volume × precision) Phase 4 pull.ts winning filters → wide pull, auto-shard, dedup, exclusions score-batch.ts scale AI qualification (gpt-5-nano by default) verify-website.ts second pass on QUALIFIED rows: live homepage fetch → dead / suspended-parked / live; live sites re-judged on their CURRENT content (catches stale-DB ghosts). Always run — DB descriptions happily qualify dead companies otherwise. Phase 5 contact-count.ts verified-email TAM ceiling (free Prospeo count trick) report.ts single-file HTML transparency report for the client
Phase 0 — inputs
- ~10 seed companies known for sure to fit (domains).
- 1–2 sentence ICP description ("multi-site medical/specialty groups in the US, ≥$3M revenue").
- Optional: exclusion CSV (companies already in campaigns).
Phase 1 — fingerprint the seeds
bashnpx tsx scripts/fingerprint.ts --domains="a.com,b.com,..." --run=<slug>
Prints coverage (which seeds Prospeo is missing — that gap IS the under-count story for the
client), plus industry and keyword-tag frequency tables. Writes fingerprint.json/csv.
Phase 2 — generate lookalikes
bashnpx tsx scripts/lookalikes.ts --domains="<seeds>" --run=<slug> \ --objective="<NL description of the COMPANY TYPE (not your product!)>" \ --country="United States #US" --pages=3
- Prospeo
company_lookalike(required lane):{"domain": "<seed>"}— one call per seed, single domain only (arrays 400). Composable with location/headcount/keyword filters. One large health system seed returned 5,727 lookalikes. - Exa findSimilar (optional lane): content similarity, and it returns homepage text in the same call — free evidence for qualification.
- Parallel.ai entity-search (optional lane): ~$0.005/req, pads to
match_limitwith junk — always qualify before trusting; returns LinkedIn URLs, not domains.
Optional lanes whose key is unset are skipped with a log line, so the run still completes on
Prospeo alone. Then qualify candidates (Claude sub-agents for a small set, or score-batch.ts
with a draft prompt) → write lookalikes-confirmed.csv. Target 50–150 confirmed.
⚠️ EXHAUSTIVE-SWEEP DEFAULT
Phase 3's scorecard is for TRANSPARENCY, not selection. The pull in Phase 4 must include: (a) EVERY industry carried by ≥1 confirmed fit — whole industry, headcount band + geo only, no keyword narrowing; (b) EVERY discriminative keyword from confirmed fits across ALL industries. Score everything with the cheap model. Only band + geography are legal pre-filters. Snowball until net-new drops under 2–3%. Never trim the sweep to save AI cost — recall is the product. Pull keywords unless they are stopword-grade.
Phase 3 — mine + score filters
bashnpx tsx scripts/mine-filters.ts --csv=<confirmed.csv> --run=<slug> --propose --country="United States #US" # Claude reviews/edits {run}/candidates.json: prune generic n-grams, add synonym keywords # (the "every medical group contains 'group'" trap — kill terms that are frequent but not discriminative) npx tsx scripts/mine-filters.ts --run=<slug> --scorecard # score the 25-company samples: for f in ~/output/list-expander/<slug>/samples/*.csv; do npx tsx scripts/score-batch.ts --csv=$f --prompt-file=<icp-prompt.txt> --out=${f%.csv}-scored.csv; done mkdir -p ~/output/list-expander/<slug>/samples-scored && mv ~/output/list-expander/<slug>/samples/*-scored.csv $_ npx tsx scripts/mine-filters.ts --run=<slug> --scorecard --precision-from=~/output/list-expander/<slug>/samples-scored
--propose fingerprints each confirmed company against Prospeo and fetches its live homepage,
then mines 2–3-grams across that combined text. The homepage is the evidence source that matters:
it says what a company calls itself today, which is exactly what a keyword filter has to match.
Pass --no-scrape to mine from Prospeo descriptions only (faster, thinner).
Output: filter-scorecard.csv — per filter: Prospeo count, sampled precision, estimated
qualified yield. Review with the user before Phase 4.
Phase 4 — wide pull + scale qualification
Tune the qualification prompt FIRST via /icp-prompt-builder (interactive, 10-company batches,
2 clean rounds to converge).
bash# Write {run}/winners.json (filter_sets + base_filters — format documented in pull.ts header) npx tsx scripts/pull.ts --run=<slug> --test # 2 pages/set sanity check FIRST npx tsx scripts/pull.ts --run=<slug> --exclude=<existing.csv> npx tsx scripts/score-batch.ts --csv=<run>/pull-all.csv --prompt-file=<icp-prompt.txt> --scrape --concurrency=8 npx tsx scripts/verify-website.ts --run=<slug> --prompt-file=<icp-prompt.txt> --concurrency=40
Verify the first test output shows real successes before the full run. Any filter set whose
total_count exceeds 24k is auto-sharded (country → 51 states → headcount-band bisection) so the
tail is never truncated.
Phase 5 — TAM ceiling + report
bashnpx tsx scripts/contact-count.ts --csv=<qualified.csv> --run=<slug> \ --titles="COO,VP Operations,..." --seniorities="C-Suite,Vice President,Head,Director" npx tsx scripts/report.ts --run=<slug> --title="<Vertical> — TAM Expansion" open ~/output/list-expander/<slug>/report.html
Requirements / env
Put these in the repo-root .env (copy .env.example), or ~/.env.
REQUIRED
| Var | What for | Sign up |
|---|---|---|
PROSPEO_API_KEY | Every phase: company search, lookalikes, counts | https://prospeo.io/ → dashboard → API (copy the X-KEY) |
OPENAI_API_KEY | AI qualification in score-batch.ts + verify-website.ts | https://platform.openai.com/api-keys |
OPTIONAL (each is one lane; unset = that lane logs skipped: <VAR> not set and the run continues)
| Var | What for | Sign up |
|---|---|---|
EXA_API_KEY | Exa findSimilar lookalike lane in lookalikes.ts | https://exa.ai/ |
PARALLEL_AI_API_KEY | Parallel.ai entity-search lookalike lane in lookalikes.ts | https://parallel.ai/ |
OPENAI_API_KEY_NANO | A separate cheap-model key; used in preference to OPENAI_API_KEY when set | https://platform.openai.com/api-keys |
OPENAI_ICP_MODEL | Override the qualification model (default gpt-5-nano) | — |
PROSPEO_MIN_INTERVAL_MS | Slow Prospeo pacing below the built-in 450ms floor. Can only make it slower — values under 450 are clamped | — |
No database is required. Every artifact is a file under ~/output/list-expander/{run}/.
Verified API facts
| Filter | Syntax | Notes |
|---|---|---|
company_lookalike | {"domain": "x.com"} or {"icp_text": "..."} | single domain only; icp_text describing the product surfaces vendors — describe the company |
company_keywords | {"include": [...], "exclude": [...]} | multi-word phrases OK; combine with company_industry for precision |
company_key_customers | {"include": [...]} | matches by who their customers are |
company_headcount_custom | {"min": N, "max": N} | use this, not headcount_range (enum format unverified) |
company_products_services, company_icp | ❌ broken/unusable via API | use company_keywords / company_lookalike.icp_text instead |
Prospeo pacing (measured): PROSPEO_MIN_INTERVAL_MS=200 (5 req/s) trips "Rate limit exceeded"
after ~1,000 requests; 450 ms (~2.2 req/s) ran 1,550+ requests clean. The account limit is
GLOBAL, so lib.ts paces every process through a shared slot file
(~/.cache/prospeo-lock/) with a 450 ms floor, backs off 45 s on a rate-limit, and makes that
penalty visible to every other running process. Identical request+page re-runs within 30 days are
FREE (free:true) — re-pulling after a partial failure costs nothing.
Prospeo count trick: a page-1 call's pagination.total_count sizes any filter cheaply; add
person_contact_details:{email:["VERIFIED"]} on /search-person for the verified-email ceiling.
Seniority enum: Founder/Owner, C-Suite, Partner, Vice President, Head, Director, Manager, Senior, Entry, Intern — never "VP", never "President".
Related skills
/icp-prompt-builder— tune the qualification prompt before Phase 4 (the score-batch script it refers to lives HERE:scripts/score-batch.ts)/prospeo-search-api— full Prospeo filter reference/prospeo-full-export— title-first paginated lead export once you have the company list/blitz-list-builder— domain-first contact discovery on the qualified companies/disco-like— a 4th lookalike source (seed domains or NL ICP text)/list-quality-scorecard— grade the final CSV before it goes anywhere near a campaign
