/prospeo-full-export

name: prospeo-full-export
description: Export your entire Prospeo people search to CSV. Build filters in Prospeo's UI, then use this skill to extract every result via the API — even searches over 25K. Handles pagination, rate limiting, deduplication, and state-by-state splitting automatically. Pair with /icp-prompt-builder on a 50-person sample to tune a qualification prompt BEFORE exporting 25K.

Prospeo Full Search Export

Extract your entire Prospeo people search to a CSV file. Build your search in Prospeo's UI, then let Claude pull every single result via the API — even if the search has more than 25,000 results.

Required step: Qualify with /icp-prompt-builder (do not skip)

Before exporting more than 500 contacts, run Prospeo on a 50-contact sample, then invoke `/icp-prompt-builder` to tune a qualification prompt in 3-5 rounds of 10 (with your approval each round). Apply the tuned prompt to the full export to filter out bad fits.

**Why required:** email enrichment downstream costs $0.05-$0.15 per person. A 25K export that's 40% wrong-fit wastes $500-$1,500 on email-finding that goes nowhere. The ICP prompt builder takes 10-15 min and saves that cost 40-70% of the time.

**Safe skip:** only if your Prospeo filter is already extremely tight (e.g., 5 exact titles + 1 industry + narrow headcount) AND you've run the same filter successfully before. Even then, run `/icp-prompt-builder` on 10 samples as a sanity check — it's nearly free to confirm.

What This Does

1. You build a search in Prospeo's web UI (filters for title, location, industry, company size, etc.) 2. You tell Claude what filters you used 3. Claude translates those filters into Prospeo API calls 4. Claude paginates through every page of results and exports to CSV 5. For large US searches (25K+), Claude automatically splits by state to get everything

Setup (First Time Only)

Step 1: Create a Prospeo Account

1. Go to [prospeo.io](https://prospeo.io) and sign up 2. Choose a plan that includes the **Search Person API** (most paid plans do) 3. Each API request that returns results costs **1 credit** and returns 25 contacts

Step 2: Get Your API Key

1. Log into Prospeo 2. Go to **Settings > API** (or visit [prospeo.io/app/settings/api](https://prospeo.io/app/settings/api)) 3. Copy your API key

Step 3: Set Your API Key

Set it as an environment variable so Claude can use it:

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export PROSPEO_API_KEY="your_api_key_here"

Then restart your terminal or run `source ~/.zshrc`.

**Security note:** Never paste your API key directly into a script file. Always use environment variables.

---

How to Use

Step 1: Build Your Search in Prospeo's UI

Go to [prospeo.io/app/search](https://prospeo.io/app/search) and use the filters to build your search. The UI lets you filter by:

• **Job title** (e.g., "CEO", "VP Sales", "Head of Marketing")
• **Location** (e.g., "United States", "California", "New York")
• **Company industry** (e.g., "Information Technology", "Healthcare")
• **Company headcount** (e.g., 11-500 employees)
• **Company technology** (e.g., "Salesforce", "HubSpot")
• **Revenue range**
• **Contact details** (has verified email, has phone number)

Note the total result count shown in the UI — you'll need this to estimate credits.

Step 2: Tell Claude Your Filters

Just describe what you filtered for. Examples:

> "I searched for CEOs and CTOs at companies with 11-500 employees in the US, in the Information Technology industry, with verified emails."

> "I'm looking for VP of Sales and Head of Sales at SaaS companies in California with 50-200 employees."

> "I need all Marketing Directors in the US at companies using HubSpot, 20-1000 headcount."

Step 3: Claude Runs the Export

Claude will: 1. Confirm the filters and estimated credit cost 2. Create a TypeScript script 3. Run it to paginate through all results 4. Export everything to a CSV file in your current directory

---

Filter Reference

These are the exact filter names the Prospeo API accepts. When you describe your search, Claude maps your description to these:

| UI Filter | API Filter Key | Format | |-----------|---------------|--------| | Job Title | `person_job_title` | `{ include: ["CEO", "CTO"], exclude: ["Intern"] }` | | Location | `person_location_search` | `{ include: ["California, United States #US"] }` | | Industry | `company_industry` | `{ include: ["Information Technology"] }` | | Headcount | `company_headcount_custom` | `{ min: 11, max: 500 }` | | Technology | `company_technology` | `{ include: ["Salesforce", "HubSpot"] }` | | Revenue | `company_revenue_custom` | `{ min: 1000000, max: 50000000 }` | | Founded Year | `company_founding_year` | `{ min: 2010, max: 2025 }` | | Company Name | `company_name` | `{ include: ["Acme"], exclude: ["Test"] }` | | Company Domain | `company_domain` | `{ include: ["acme.com"] }` | | Has Email | `person_contact_details` | `{ email: ["VERIFIED"] }` | | Has Phone | `person_contact_details` | `{ mobile: ["TRUE"] }` | | Exact Title Match | `person_job_title` | `{ include: [...], match_only_exact_job_titles: true }` |

Location Format

Locations must follow this exact format:

• Country: `"United States #US"`, `"United Kingdom #GB"`, `"Canada #CA"`
• State: `"California, United States #US"`, `"Texas, United States #US"`
• City: `"San Francisco, California, United States #US"`

Headcount Ranges (Common Presets)

| Label | min | max | |-------|-----|-----| | 1-10 | 1 | 10 | | 11-50 | 11 | 50 | | 51-200 | 51 | 200 | | 201-500 | 201 | 500 | | 501-1000 | 501 | 1000 | | 1001-5000 | 1001 | 5000 | | 5001-10000 | 5001 | 10000 | | 10001+ | 10001 | (omit max) |

---

API Details

**Endpoint:** `POST https://api.prospeo.io/search-person`

**Auth:** `X-KEY` header with your API key

**Rate Limit:** 2 requests per second (the script handles this automatically)

**Pagination:** 25 results per page, max 1000 pages = **25,000 r