prospeo-search-api

Prospeo Search Person API

This skill documents how to use the Prospeo Search Person API for finding leads with filters.

When to Use

Use this skill when:

• Searching for people/leads by job title, industry, location, company size, etc.
• Building lead lists from Prospeo's database
• Running large US-wide searches that need state-by-state crawling

API Overview

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

Authentication: X-KEY header with API key

Rate Limits:

• 2-2.5 requests/second (120-150 req/min)
• Token bucket implementation recommended

Result Limits:

• 25 results per page
• 1000 pages max = 25,000 results per search
• 1 credit per search request that returns at least 1 result

Request Format

POST /search-person
Headers: {
  'Content-Type': 'application/json',
  'X-KEY': process.env.PROSPEO_API_KEY
}
Body: {
  page: number,        // 1-1000
  filters: ProspeoSearchFilters
}

Filter Types

interface ProspeoSearchFilters {
  // Location (use "State, United States #US" format)
  person_location_search?: {
    include?: string[];  // e.g., ["California, United States #US"]
    exclude?: string[];
  };

  // Job titles
  person_job_title?: {
    include?: string[];  // e.g., ["CEO", "Founder"]
    exclude?: string[];
    match_only_exact_job_titles?: boolean;
  };

  // Company size
  company_headcount_custom?: {
    min?: number;  // e.g., 11
    max?: number;  // e.g., 500
  };

  // Industry
  company_industry?: {
    include?: string[];  // e.g., ["Information Technology"]
    exclude?: string[];
  };

  // Technology stack
  company_technology?: {
    include?: string[];  // e.g., ["Salesforce", "HubSpot"]
    exclude?: string[];
  };

  // Contact requirements
  person_contact_details?: {
    email?: string[];   // ["VERIFIED"] for verified emails only
    mobile?: string[];
    operator?: string;
  };

  // Duplicate control
  person_duplicate_control?: {
    hide_people_from_all_my_lists?: boolean;
    hide_people_already_exported_before?: boolean;
  };

  // Funding (use this for "recently raised Series X" targeting)
  company_funding?: {
    // Days since last funding round. Valid values: 90, 180, 270, 365, or null (None).
    // Maps to UI dropdown "Select last funding round date".
    funding_date?: 90 | 180 | 270 | 365 | null;

    // Last funding round amount (bucketed enum range).
    // Valid bucket values: "<100K", "100K-500K", "500K-1M", "1M-5M", "5M-10M",
    // "10M-25M", "25M-50M", "50M-100M", "100M-500M", "500M+", "Max"
    last_funding?: { min?: string; max?: string } | null;

    // Total funding raised across all rounds (same bucketed enum range as last_funding).
    total_funding?: { min?: string; max?: string };

    // Funding stage checkboxes. Valid values:
    //   "Pre seed", "Seed", "Series unknown", "Series A", "Series B",
    //   "Series C", "Series D", "Series E-J",
    //   "Grant", "Angel", "Private equity", "Debt financing",
    //   "Non equity assistance", "Post IPO equity", "Undisclosed",
    //   "Post IPO debt", "Product crowdfunding", "Equity crowdfunding",
    //   "Corporate round", "Convertible note", "Secondary market",
    //   "Initial coin offering", "Post IPO secondary"
    stage?: string[];
  };

  // Company filters
  company_name?: { include?: string[]; exclude?: string[] };
  company_domain?: { include?: string[]; exclude?: string[] };
  company_revenue_custom?: { min?: number; max?: number };
  company_founding_year?: { min?: number; max?: number };
}