/01-prospeo-lookalike

name: 01-prospeo-lookalike
description: >
  Seed-based B2B company discovery via the Prospeo company-lookalike API. Use when the
  user has example companies and wants more like them - "find companies similar to X",
  "companies like Stripe and HubSpot", "lookalikes of these domains", "we closed these
  20 logos, find more", "expand this seed list", or hands over closed-won accounts / a
  competitor / a customer list and wants similar firmographic matches. Turns seed domains
  or an ICP description into a ranked list of similar companies, and can also hand a
  pattern-built ICP to prospeo-discover for a broader search.

Prospeo Lookalike - Seed-Based Company Discovery

Turn seed companies (domains, an ICP description, or "similar to X") into similar companies via Prospeo's `company_lookalike` filter (33-filter, 30M+ company database). Two ways to finish:

• **Mode 1 - Lookalike list** (headline): return the actual similar companies, ranked by similarity

tier. The lookalike filter runs *alone* - no ICP stacking - so you get a full list, not single digits.

• **Mode 2 - Seed → ICP handoff**: analyze the 25 closest matches for patterns, build an ICP, and hand

it to [`01-prospeo-discover`](../01-prospeo-discover/SKILL.md) for a broad firmographic search.

Discovery (skill 01) deliberately treats lookalike as a throwaway pattern-finder and drops it before its real search. This skill is the opposite - here the lookalike matches are a first-class deliverable.

Your job

1. Collect the seed(s) - domains, named companies, or an ICP paragraph - and pick the mode. 2. Resolve seeds to what the API needs (domain string, company IDs, or `icp_text`). 3. Run the lookalike search, present the ranked matches with the similarity tier. 4. Offer the next step: export the list (Mode 1) or build an ICP and route to discovery (Mode 2).

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, incl. lookalike (1 credit per page)
• `POST /search-suggestions` - resolve locations, technologies, industries, 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": {"company_lookalike": { ... }}, "page": 1}'

Full curl formats, the search-suggestions key table, and the 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. Store them.

**Lookalike needs Starter or higher.** `company_lookalike` is filter #22, gated to **Starter+** (see `references/plan-filter-map.md`). On the **Free** plan it is unavailable - if the account is Free, say so up front and stop, rather than assembling a search that will fail:

> Lookalike needs a Starter plan or higher; this account is on Free. I can still build a list from an ICP > description with `01-prospeo-discover` instead.

If `remaining_credits` is under 10, tell the user their balance and that each page costs 1 credit before spending anything.

**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. You only need enums when the user layers ICP constraints (industry, size, etc.) onto the lookalike or when you build the Mode 2 ICP. Technologies (4,946) and locations resolve at runtime via `search-suggestions`.

Then present a clean prompt and wait for input.

Prospeo Lookalike ready.
Plan: {plan} | Credits: {credits}

Give me the seed companies you want to find matches for - domains, names, or a short
description of the ideal company.

Step 1 - Collect seeds and resolve them

The lookalike filter takes exactly ONE mode per call. Pick by what the user gave you:

| What the user gave | Mode | How to build it | |---|---|---| | One domain ("similar to hubspot.com") | **domain** | `{"domain": "hubspot.com"}` - no lookup needed | | Multiple domains / named companies | **company_oids** | Resolve each to a Prospeo company ID first, then `{"company_oids": [...]}` | | A paragraph describing the ideal company | **icp_text** | `{"icp_text": "..."}` (max 5,000 chars) - no lookup needed |

**Resolving multiple domains to company IDs** (1 credit each): search `company.websites.include` for each domain, read the company ID off the result, collect the IDs. Full detail and the exact response field