keinsaasforever/gtm-pipeline-skills/gtm-people-search

People Search

Find contacts at specific companies or by persona. Returns a CSV with LinkedIn profile URLs, ready for enrichment.

Read `~/.claude/skills/gtm-pipeline/_shared/conventions.md` before executing.

When to Use

• You have a company list and need contacts with specific roles
• You need to build a persona-based prospect list (no company list)
• A demo was triggered and you need ~10 contacts matching a prompt

Inputs

If company domains are missing, use SerpAPI domain lookup first (see Step 0 below).

Step 0: Domain Lookup (SerpAPI) — When Domains Are Missing

Most people-search APIs require domains, not LinkedIn URLs.

GET https://serpapi.com/search
  ?engine=google_light
  &q={company_name}
  &location={target_country}
  &google_domain={country_google_domain}
  &api_key=YOUR_KEY

Extract domain:

import urllib.parse
organic = response.get("organic_results", [])
link = organic[0].get("link", "")
domain = urllib.parse.urlparse(link).netloc.lstrip("www.")

Spot-check all domains before using — SerpAPI returns wrong results for generic names and global brands.

Env var: SERPAPI_API_KEY

Provider Selection

Company mode (have company list)

Finder cadence (segment-routed waterfall): FullEnrich Finder → BetterContact Lead Finder → Pipe0 searches (`amplemarket@2` → `crustdata@3` → `parallel@1`, last resort). Max 2 attempts per source (e.g. a title-token query then a name-only query), then fall through. Lead with FullEnrich for SME / owner-led / non-English-market segments (better indexed there); lead with BetterContact for broader / English-market / larger companies. Add a Pipe0 pass on whatever the finders missed — different index, additive coverage. See conventions "People-Source Cadence" for the full waterfall and fallback rule; the table below is per-provider mechanics and cost, not a fixed running order.

Indexes barely overlap on small EU SMEs — running FE → amplemarket@2 → crustdata@3 is additive, not redundant. In an April 2026 DACH e-commerce run (81 FE-missed shops): amplemarket recovered 29 shops (74 contacts, 35%), crustdata added 1 more shop as fallback. Amplemarket stays first: 3.00 flat for up to 100 rows beats crustdata's 3.75 worst case for 25.

Two-tier search pattern (proven on EU e-commerce campaigns):

1. Tier 1 — E-commerce + Marketing titles (always run)
2. Tier 2 — Leadership titles (CEO/MD/Founder) — only if Tier 1 returns 0 contacts AND company traffic ≤ 200K visits/month (large shops likely have dedicated e-comm/marketing staff indexed by FE)

Run the same two-tier logic on whichever finder leads the cadence for the segment (FE or BC). BC cost is per-request regardless of results; FE cost is per-person returned.

When PhantomBuster is selected: read _shared/phantombuster.md and use the /phantombuster skill to generate the script. Phantom scripts: "LinkedIn Company Employees Export" (config key PB_AGENT_EMPLOYEES) and "Sales Navigator Search Export" (config key PB_AGENT_SN_SEARCH).

Persona mode (no company list)

Persona mode has no company anchor, so an unfiltered search is a fully-billed market-wide dump. Never send a persona search without both a title list and at least one resolved region — the repo's builder raises on either being empty (see Provider E).

Do NOT use Parallel Task enrichment for people — model guesses titles, returns wrong roles. Use FindAll.

Manual / one-time

Both BetterContact and FullEnrich dashboards offer free search without API credits.

Execution Protocol

1. Sandbox / Docs Check

• Verify request/response structure with 1 record, zero cost
• For Pipe0: use "environment": "sandbox"
• For FE/BC: review docs or test via dashboard

2. Test Batch (15 companies or 15 records)

• Run chosen provider on 15 companies in production
• Print and review every row: company names, contact names, job titles, locations, LinkedIn URLs
• Check for global domain contamination (BC: add lead_location filter for .com domains)
• Assess hit rate, data completeness, relevance

3. Review with User

• Present test results with hit rate and sample rows
• Flag issues (wrong country, irrelevant titles, missing LinkedIn URLs)
• Suggest improvements or provider switch if results are poor
• Get approval before full run

4. Full Run

• Submit remaining companies (skip test batch)
• Save request IDs to file immediately (recovery if crash)
• Poll with sufficient timeout
• Save results incrementally to CSV after each batch

5. Consolidation

• Merge test + full run results
• Deduplicate by LinkedIn URL (fallback: name + company)
• Clean names/titles (.title(), strip whitespace)
• Add source column
• Write to csv/intermediate/contacts_found.csv

Provider A: FullEnrich Finder

Endpoint: POST https://app.fullenrich.com/api/v2/people/search Auth: Authorization: Bearer $FULLENRICH_API_KEY Cloudflare: call with curl + a browser User-Agent — Python requests/urllib get blocked (error 1010). Never ship a urllib-based provider script. See conventions rule #8. Domain-keyed index: the Finder is keyed on company domain and misses orgs whose domain differs from the indexed one — prefer name-based search (current_company_names + location) over the domain filter; validate hits by domain-root or name token.

Request

{
  "offset": 0,
  "limit": 100,
  "current_company_domains": [
    {"value": "example.com", "exact_match": true, "exclude": false}
  ],
  "current_position_titles": [
    {"value": "Marketing Manager", "exact_match": false, "exclude": false},
    {"value": "Head of Marketing", "exact_match": false, "exclude": false}
  ],
  "person_locations": [
    {"value": "South Africa", "exact_match": false, "exclude": false}
  ]
}

Available Filters

All filters support exclude: true for negative matching. Multiple filters within same field = AND logic.

Pagination: offset + limit (max 100/page, max offset 10,000). Beyond 10k: use search_after cursor.

Response

Response fields are nested — current_position_title and linkedin_url do NOT exist at top level.

⚠ LinkedIn URL path gotcha: the URL lives under social_profiles.professional_network.url, NOT social_profiles.linkedin.url. Older notes/snippets used .linkedin.url and silently returned empty strings for every row. Always parse professional_network first.

Also: the seniority field is seniority (not seniority_level) at employment.current.seniority. Values include Manager, Senior, Head, Director, VP, C-Level.

people = response.get("people", [])
for person in people:
    name        = person.get("full_name", "")
    current     = (person.get("employment", {}) or {}).get("current", {}) or {}
    title       = current.get("title", "")
    seniority   = current.get("seniority", "")
    social      = person.get("social_profiles", {}) or {}
    li_url      = (social.get("professional_network", {}) or {}).get("url", "")
    loc_obj     = person.get("location", {}) or {}
    location    = f"{loc_obj.get('city', '')}, {loc_obj.get('country', '')}".strip(", ")
    # company info also nested: current["company"]["name"], current["company"]["domain"]