/01-prospeo-discover

name: 01-prospeo-discover
description: >
  B2B company discovery and list building via the Prospeo search API. Use when the
  user wants to find companies from an ICP, build a prospect or TAM list, search by
  ICP, or size a market - e.g. "build a list of B2B SaaS in the US", "how many companies
  match this ICP", "TAM sizing", "company search", or any mix of industry + location +
  headcount + funding filters. Handles seed-based "similar to X" requests too by building an
  ICP from the seeds; 01-prospeo-lookalike is the deeper specialist when you want the matches
  themselves returned and ranked.

Prospeo Discover - B2B Company List Builder

Turn a plain-English ICP into Prospeo filter JSON, run a company search against Prospeo's 30M+ company database (33 filters), present the result, and export to Google Sheets on request.

Your job

1. Work out what the user has given you and what's still missing. 2. Map their language to exact Prospeo filter values. Resolve anything you're unsure of via the API rather than inventing enum values. 3. Cover the mandatory filters, using the smart defaults below for anything they skip. 4. Recommend a few high-impact optional filters, then stop. 5. Run the search, show the count plus a 25-row preview, and export only when asked.

Credits are real money: each search page costs 1 credit; account and suggestion calls are free. Guard spend, especially on export.

Setup

Auth reads from environment variables. Nothing is hardcoded.

• `PROSPEO_API_KEY` - required for every Prospeo call.
• Google Sheets export reads OAuth credentials from `GOOGLE_TOKEN_PATH` (default `~/.google/token.json`). Only needed when exporting.

The curl examples use `$PROSPEO_API_KEY` as the key. **A `.env` file is not visible to curl** - load it into the shell first, in the same command as the call, or curl sends an empty `X-KEY` header and the API returns a confusing auth error instead of a missing-key one:

set -a; [ -f .env ] && . ./.env; set +a
curl -s -H "X-KEY: $PROSPEO_API_KEY" https://api.prospeo.io/account-information

Check `$PROSPEO_API_KEY` is non-empty before the first paid call. The Python scripts under `scripts/` read `.env` themselves and need no such prelude.

API basics

Base URL: https://api.prospeo.io
Auth header: X-KEY: $PROSPEO_API_KEY
Content-Type: application/json

Three endpoints:

• `GET /account-information` - plan and credit balance (free)
• `POST /search-company` - the search (1 credit per page)
• `POST /search-suggestions` - resolve locations, technologies, industries, and other open-ended values (free)

The one body-shape rule that breaks searches when you get it wrong: filters go inside a `"filters": {}` wrapper, and `"page"` is a sibling of `"filters"`, not inside it.

curl -s -X POST "https://api.prospeo.io/search-company" \
  -H "X-KEY: $PROSPEO_API_KEY" -H "Content-Type: application/json" \
  -d '{"filters": { ...filter JSON... }, "page": 1}'

`search-suggestions` takes exactly one search key per request (min 2 chars) and is how you resolve any value you are not certain of. The full table of search keys and response keys, the worked curl examples, and the wrong formats to avoid live in `references/api-curl.md` - read it before resolving values for the first time in a session.

Step 0 - Plan and enum check (internal, run once)

Do this silently before prompting the user. Don't narrate it or show step numbers.

**Plan and credits.** Call `GET /account-information` and read `current_plan` and `remaining_credits` from the `response` object (plus the renewal date if the response carries one). Store them. If `remaining_credits` is under 10, tell the user their balance and that each page costs 1 credit before spending anything.

Gate filters by plan. Only offer what the plan supports, and don't ask about filters it lacks. Full mapping in `references/plan-filter-map.md`:

• **Free**: 18 filters (no revenue, funding, technology, lookalike, or job postings)
• **Starter**: adds revenue, funding, technology, lookalike, job postings
• **Growth**: adds ICP, integrations, awards, key customers, headcount-by-location
• **Pro**: all 33 (adds exec changes, website traffic/search, SEO keywords)

**Enum cache.** Read `references/prospeo-enums.json` and check `last_updated`. If it's missing or older than 21 days, refresh it with `references/enum-refresh.md`; otherwise use the cached values. The cache holds valid values for industries (256), subtypes, funding stages, employee and revenue ranges, departments, and more. Technologies (4,946) and locations are too large to cache - resolve those at runtime via `search-suggestions`.

If the invoking request already describes the ICP - which is the common case - go straight to mapping it; don't re-ask for what you were just told. Only when you have nothing to work from, ask what companies they're looking for, mentioning the plan and credit balance. Don't show examples or sample company names.

Step 1 - Read the input, pick the approach

Sort what the user gave you into three buckets:

• **ICP filters** - industry, size, location, funding, revenue, keywords, company type
• **Seed signals** - seed domains, "similar to X", named companies to match
• **Vague terms** that need mapping - "tech", "healthcare", "fintech"

That tells you how to proceed. You don't need to announce a "type" to the user, just route:

| What they gave | Approach | |---|---| | A full ICP (4-5 mandatory filters covered) | Map it to filter JSON and confirm | | A partial or vague ICP | Guide them: interpret vague terms against the enum cache, then ask for missing mandatory filters one at a time with smart defaults | | Seed domains or "similar to" | Build an ICP from the seed pattern (see below), then search |

A user can hand you a partial ICP *and* a seed domain - build the ICP from the seeds (below), merge it with the filters they already gave, and run the search.

Mandatory filters and smart defaults