| name | gtm-pipeline:people-search |
| description | Find contacts at specific companies or by persona. Use when you have a company list and need contacts with specific roles (company mode), or when building a persona-based prospect list without a company list (persona mode). Also triggers on "find contacts", "search for people at [company]", "find [role] contacts", "people search". |
People Search
Find contacts at specific companies or by persona. Returns a CSV with LinkedIn profile URLs, ready for enrichment.
Read .agents/skills/_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
| Input | Required | Source |
|---|
| Company list (CSV with names + domains) | For company mode | Company Search / Company Enrichment output, or user-provided |
| Target roles / job titles | Yes | User prompt or ICP definition |
| Location filter | Recommended | User prompt or ICP definition |
| Search mode | Yes | company (have company list) or persona (no company list) |
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)
Default flow: BetterContact first → FullEnrich fallback if BC returns 0 contacts. For DACH SMEs, add a Pipe0 Amplemarket pass on whatever FE missed — different index, additive coverage.
| Priority | Provider | Cost | LinkedIn URLs | Key Strength |
|---|
| 1st | BetterContact Lead Finder | 0.10 cr/request | Yes | Cheaper fixed cost; good for high-volume batches |
| 2nd | FullEnrich Finder | 0.25 cr/person | Yes | Richest filters; richer fields (seniority, headcount, industry) |
| 3rd | Pipe0 Amplemarket | 3.00 cr/page (≤100 results) | Yes | Cheap waterfall for FE/BC misses — separate index covers different shops (+36% shop coverage on DACH SMEs where FE had 0 hits). Supports company domain + name filters |
| 4th | Pipe0 Crustdata | 5.00 cr/page | Yes | Final fallback — low additive value when run after Amplemarket (+1 shop out of 81 in DACH test) |
| 5th | PhantomBuster Company Employees Export | Free (LinkedIn account) | Yes | Good when SN not available; scrapes directly from LinkedIn company page |
| 6th | PhantomBuster SN Search Export | Free (SN account) | Yes | Full SN search power; use when you have a saved SN search URL |
Indexes barely overlap on small EU SMEs — running FE → Amplemarket → Crustdata 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. Always run cheapest provider first.
Two-tier search pattern (proven on EU e-commerce campaigns):
- Tier 1 — E-commerce + Marketing titles (always run)
- 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 for both BC (primary) and FE (fallback). 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)
| Priority | Provider | Cost | Key Strength |
|---|
| 1st | Parallel FindAll | varies by processor | Discover people matching criteria from web sources |
| 2nd | BetterContact Search | TBD | Search without company filter |
| 3rd | Pipe0 Amplemarket | 3.00 cr/page | Structured filters (location, industry, employer revenue, founded year, departments, seniority) |
| 4th | Pipe0 Crustdata | 5.00 cr/page | Richest persona filters (experience, seniority, skills, education, certifications, career movement) |
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
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
| Filter | Type | Example |
|---|
current_company_names | object[] | {"value": "Anthropic", "exact_match": true} |
current_company_domains | object[] | {"value": "google.com", "exact_match": true} |
current_company_linkedin_urls | object[] | LinkedIn company URL |
current_company_industries | object[] | "Software Development" |
current_company_types | object[] | "Public Company", "Privately Held" |
current_company_headquarters | object[] | "San Francisco" |
current_company_headcounts | object[] | {"min": 50, "max": 200} |
current_company_founded_years | object[] | {"min": 2020, "max": 2024} |
current_position_titles | object[] | "Chief Technology Officer" |
current_position_seniority_level | object[] | "Director", "VP", "C-level" |
past_position_titles | object[] | Past job title |
past_company_names / domains | object[] | Previous employer |
person_names | object[] | "John Smith" |
person_linkedin_urls | object[] | Direct LinkedIn URL lookup |
person_locations | object[] | "South Africa", "California" |
person_skills | object[] | "JavaScript", "Project Management" |
current_position_years_in | object[] | {"min": 0, "max": 1} (new in role) |
current_company_years_at | object[] | {"min": 2, "max": 5} (tenure) |
person_universities | object[] | "Stanford University" |
current_company_days_since_last_job_change | object[] | {"min": 0, "max": 90} (recent hires) |
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.
people = response.get("people", [])
for person in people:
name = person.get("full_name", "")
title = person.get("employment", {}).get("current", {}).get("title", "")
li_url = (person.get("social_profiles", {}) or {}).get("linkedin", {}).get("url", "")
loc_obj = person.get("location", {})
location = f"{loc_obj.get('city', '')}, {loc_obj.get('country', '')}".strip(", ")
Key Notes
current_company_linkedin_urls filter accepts LinkedIn company URLs directly (e.g. https://www.linkedin.com/company/dojo-tech/) — no domain lookup needed when you have LinkedIn company URLs in your input CSV- Hit rate for EU SME audience (via LinkedIn URL filter): ~48% (15/31 companies). Very small/niche companies with few employees often have low FE index coverage — expect 0 results.
Cost
0.25 credits per person returned.
Docs
https://docs.fullenrich.com/api/v2/people/search/post
Provider B: BetterContact Lead Finder
Endpoint: POST https://app.bettercontact.rocks/api/v2/lead_finder/async
Auth: X-API-Key: $BETTERCONTACT_API_KEY
Submit
{
"filters": {
"company": {
"include": ["virginactive.co.za"]
},
"lead_location": {
"include": ["South Africa"]
},
"lead_job_title": {
"include": [
"marketing manager", "head of marketing", "brand manager",
"marketing director", "CMO", "digital marketing"
],
"exact_match": false
}
},
"max_leads": 10
}
Returns: { "success": true, "request_id": "abc123" }
Poll
GET https://app.bettercontact.rocks/api/v2/lead_finder/async/{request_id}
Done when: response["status"] == "terminated" (not "completed")
Typical wait: 30–60 seconds per request.
Parse
leads = response.get("leads", [])
for lead in leads:
name = lead.get("contact_full_name", "")
title = lead.get("contact_job_title", "")
li_url = lead.get("contact_linkedin_profile_url", "")
company = lead.get("company_name", "")
domain = lead.get("company_domain", "")
country = lead.get("contact_location_country", "")
co_li = lead.get("company_linkedin_url", "")
Global Domain Contamination
When using a global domain (.com for Samsung, H&M, Amazon, etc.), BetterContact returns employees from all countries. Always add "lead_location": {"include": ["Target Country"]} for global-domain companies. Local ccTLD domains (.co.za, .de) are safe without it.
Cost
0.10 credits per request (fixed, regardless of number of leads returned or zero results).
Fields Returned
BC returns fewer fields than FE — no seniority, companyHeadcount, companyIndustry, or roleStartDate. Derive linkedinProfileSlug from the LinkedIn URL (/in/<slug>). Split contact_full_name into first/last manually.
Filter Compatibility
When filtering contacts by job title keyword, BC uses contact_job_title (not FE's nested employment.current.title). Ensure your filter function checks both:
title = (p.get("current_position_title") or
p.get("contact_job_title") or
p.get("employment", {}).get("current", {}).get("title") or "")
Hit Rate
- SA marketing roles, local (.co.za): ~65–70%
- DACH SME (March 2026): 1/3 companies (33%) — BC missed 2/3; FE found contacts at 2/3 on same set
- EU furniture e-commerce SME (April 2026): ~15–20% overall; T2 leadership tier recovers ~10% more
When BC Finds Nothing
Fall back to FullEnrich. BC has lower index coverage for small EU SMEs, especially IT/PL markets. FE's richer filters and larger index often surface contacts BC misses — and vice versa. Running both covers ~25–30% of shops vs ~20% with either alone.
Docs
https://doc.bettercontact.rocks/api-reference/endpoint/lead_finder_post
Provider C: Parallel FindAll (Persona Mode)
Endpoint: POST https://api.parallel.ai/v1beta/findall/runs
Required header: parallel-beta: findall-2025-09-15
Auth: x-api-key: $PARALLEL_API_KEY
Always ask which processor to use: core, core2x, pro, ultra
Request
{
"objective": "Find heads of marketing at e-commerce companies in South Africa with 50-500 employees",
"entity_type": "people",
"match_conditions": [
{"name": "role", "description": "Person must hold a marketing leadership role (Head of Marketing, CMO, Marketing Director)"},
{"name": "location", "description": "Person must be based in South Africa"},
{"name": "company_size", "description": "Company must have roughly 50-500 employees"}
],
"generator": "core",
"match_limit": 25
}
Writing good objectives:
- Write like a research brief — detailed, with source guidance
- Describe what signals/sources to start from, not just what to find
- Include geographic, industry, and size constraints in the objective text AND as match_conditions
Poll
GET /v1beta/findall/runs/{findall_id} # status
GET /v1beta/findall/runs/{findall_id}/result # results when complete
Timeout: 15 min for core/core2x, 30 min for pro/ultra
Enrich FindAll Results
After FindAll, add structured fields:
POST /v1beta/findall/runs/{findall_id}/enrich
Always include company_website and linkedin_company_url in output schema.
Rules
- Always ask which processor to use — never decide without asking
- Never re-run before reviewing results
- Present the full request payload for review before executing
- Assess accuracy using confidence score and reasoning
Docs
Always check latest docs via context7 (libraryName: parallel-web) before building — endpoints and parameters evolve.
Provider E: Pipe0 Amplemarket (Filter-Based)
Endpoint: POST https://api.pipe0.com/v1/search/run/sync (singular search)
Search ID: people:profiles:amplemarket@1
Auth: Authorization: Bearer $PIPE0_API_KEY
Use curl — Python requests blocked by Cloudflare.
Best for: Company-mode fallback when FE/BC miss (cheap at 3 cr/page) AND persona-mode filter search.
Request (Company Mode)
{
"config": {"environment": "production", "dedup": {"strategy": "default"}},
"search": {
"search_id": "people:profiles:amplemarket@1",
"config": {
"limit": 5,
"filters": {
"current_employer_website_urls": {"include": ["example.com"]},
"current_employer_names": {"include": ["Example GmbH"]},
"current_job_titles": ["CEO", "Geschäftsführer", "Founder", "Head of Marketing"],
"current_locations": {"include": ["Germany"]}
}
}
}
}
⚠ Filter Format Gotcha (Amplemarket-specific)
current_job_titles must be a PLAIN ARRAY (["CEO", "Founder"]), NOT {"include": [...]} like the other fields. Crustdata uses the object form. Getting it wrong → 422 validation error.- Most other filters use the
{"include": [...], "exclude": [...]} object form.
Available Filters (discovered via sandbox probe)
person_names, school_names,
current_locations, current_job_titles, current_departments,
current_job_functions, current_seniority_levels,
current_employer_names, current_employer_website_urls,
current_employer_linkedin_industries, current_employer_locations,
current_employer_investors, current_employer_founded_year,
current_employer_estimated_revenue, current_employer_open_positions_titles
Response
results = response.get("results", [])
for r in results:
name = r.get("name", {}).get("value", "")
title = r.get("job_title", {}).get("value", "")
li_url = r.get("profile_url", {}).get("value", "")
co_url = r.get("company_website_url", {}).get("value", "")
match = r.get("amplemarket_person_match", {}).get("value", {})
Key Notes
- Fuzzy title match: titles are OR-matched loosely. A request for
["CEO", "Founder"] returned a "Product Owner" at one of the test shops. Post-filter on title if strict role matching matters.
- Location/country filter is highly reliable — use it.
- Sandbox is free (
"environment": "sandbox") — always probe filter shape with 1 record before spending credits. Sandbox returns fake data but validates the request schema.
Cost
3.00 credits per page (up to 100 results). Paying per page — so limit: 5 still costs 3 cr.
DACH SME Hit Rate
- Company-mode on FE-missed DACH e-commerce SMEs: 28/81 shops (35%) as primary search
- Avg 2.5 contacts per hit shop, 74 contacts total
- Company filter accepts both
current_employer_names and current_employer_website_urls; domain form works with or without https:// prefix
Provider F: Pipe0 Crustdata (Filter-Based)
Endpoint: POST https://api.pipe0.com/v1/search/run/sync (singular search)
Search ID: people:profiles:crustdata@1
Best for: Last-resort fallback after Amplemarket. Also strong for persona searches needing experience/seniority/skill filters.
Request (Company Mode — yes, Crustdata DOES support company filters)
{
"config": {"environment": "production", "dedup": {"strategy": "default"}},
"search": {
"search_id": "people:profiles:crustdata@1",
"config": {
"limit": 5,
"filters": {
"current_employers_website_urls": {"include": ["example.com"]},
"current_employers": {"include": ["Example GmbH"]},
"current_job_titles": {"include": ["CEO", "Geschäftsführer"]},
"locations": {"include": ["Germany"]}
}
}
}
}
Filter Format
- Everything uses the
{"include": [...], "exclude": [...]} object form — including current_job_titles. This is the opposite of Amplemarket's plain-array form for titles.
Available Filters (discovered via sandbox probe)
honors, skills, languages, locations,
degree_names, school_names, certifications, fields_of_study,
current_employers, current_employers_website_urls,
current_employers_linkedin_industries,
current_job_titles, current_school_names, current_seniority_levels,
previous_employers, previous_employers_website_urls,
previous_employers_linkedin_industries,
previous_job_titles, previous_seniority_levels,
profile_languages, profile_headline_keywords, profile_summary_keywords,
years_of_experience, years_at_current_company, recently_changed_jobs,
extracurricular_activities
Response
Same shape as Amplemarket. Match field: crustdata_person_match.value.
Cost
5.00 credits per page (100 records). More expensive than Amplemarket — run it AFTER Amplemarket for company-mode fallback, not before.
DACH SME Hit Rate
- As Amplemarket-fallback on DACH e-commerce SMEs: 1/52 shops Amplemarket missed = very low additive value. Worth skipping if budget is tight.
- Stronger in persona mode where its experience/skill/certification filters matter.
When NOT to use
- As primary company-mode search → Amplemarket is 40% cheaper and has comparable DACH coverage
- If Amplemarket already returned results for the shop → don't double-pay
Output
CSV saved to csv/intermediate/contacts_found.csv:
company_name, company_domain, company_linkedin_url,
first_name, last_name, full_name,
job_title, linkedin_profile_url, source
All original input columns preserved. Always include a source column (e.g. fullenrich_finder, bettercontact_lead_finder, pipe0_amplemarket, pipe0_crustdata, parallel_findall).
Key Rules
- Default flow: BC → FE fallback. Run BetterContact first (cheaper fixed cost). If BC returns 0 filtered contacts, run FullEnrich as fallback. Track BC and FE credits separately.
- Two-tier search: Always run Tier 1 (e-commerce/marketing titles). Only run Tier 2 (leadership) if Tier 1 returns 0 AND company is below traffic threshold (e.g. ≤ 200K monthly visits).
- Global domains require location filter in BetterContact (
.co.za safe; .com for global brands returns worldwide).
- BC is async — submit then poll every 5s until
status == "terminated". Typical wait: 30–60s per request. Budget accordingly for large batches.
- Senior titles bypass keyword filter — "Head of", Founder, Director, C-level always pass regardless of excluded keywords (e.g. "Head of Marketing & Brand" should not be excluded for "brand").
- Pipe0: use curl via subprocess — Python requests blocked by Cloudflare.
- Never re-run before reviewing results — save request IDs, poll for results, don't double-submit.
- Unicode in company names — CSV may use curly apostrophes (
\u2019). Use repr() to debug string comparison failures.
Google Sheets Row Matching (when writing results back)
When updating shop/lead status in a Google Sheet, build a lookup map at load time rather than calling ws.find() (which fails on large sheets):
domain_row_map = {}
merchant_row_map = {}
for row_num, row in enumerate(all_values[1:], start=2):
d = clean_domain(row[col["domain"]])
if d:
domain_row_map[d.lower()] = row_num
m = row[col["merchant_name"]].strip()
if m:
merchant_row_map[m.lower()] = row_num
In update_status(), look up by domain first, fall back to merchantName if not found — handles domains stored with www. prefix or other mismatches.
What's Missing (To Document)
- BetterContact Search (persona mode) — API endpoint and usage
- Exa Websets via Pipe0 for people discovery
- Pipe0 Crustdata company-mode hit rates as PRIMARY search (currently only measured as AM-fallback)
