Email Search

Email Finder

Turn LinkedIn profiles into verified emails and phones. Takes the output of people-search and runs it through contact enrichment providers like Prospeo or Fullenrich.

Related Skills

list-segmentation → people-search → email-search → email-generation → email-response-simulation → campaign-sending

After people-search finds WHO to contact (with LinkedIn URLs), this skill gets their verified contact info.

Extruct API Operations

This skill delegates all Extruct API calls to the extruct-api skill.

For all Extruct API operations, read and follow the instructions in skills/extruct-api/SKILL.md.

The only Extruct operation in this skill is reading people table data. Contact enrichment uses separate providers (Prospeo, Fullenrich, etc.) with their own APIs.

Inputs

Choosing a Provider

Ask the user which contact enrichment provider they want to use. If they need guidance, consider:

• Have LinkedIn URLs? → providers with LinkedIn enrichment work best
• Need highest email hit rate? → waterfall providers try multiple sources
• Budget-conscious? → check credit costs per match
• Need mobile phones? → confirm the provider covers phone data
• Want maximum coverage? → run one provider first, then a second for misses

If the user doesn't know where to start, pre-configured options with local reference docs are available in references/.

Workflow

Step 0: Confirm provider and learn API

1. Ask the user which contact enrichment provider they want to use 2. Fetch or read the provider's API documentation and identify:

• Enrichment endpoint (single and bulk)
• Required input fields (LinkedIn URL, name, domain, etc.)
• Authentication method and credentials
• Throughput limits and request constraints
• Response format (email, phone, verification status)
• Credit/pricing model

3. Ask for their API credentials and confirm access 4. Plan the implementation and confirm with the user before proceeding

Step 1: Load people data

Option A: From Extruct people table (recommended) — Use the extruct-api skill to fetch data from the people table. Extract full_name, profile_url, role, and parent_row_id from each row. Split full name into first/last.

Option B: From CSV — Read claude-code-gtm/csv/input/{campaign}/people_linkedin.csv.

Step 2: Check credits

Before running enrichment, check the user's available credits or quota with the chosen provider (using the endpoint identified in Step 0). Present a cost estimate based on the number of contacts to enrich.

Step 3: Run enrichment

Using the chosen provider's API (from Step 0):

1. Prepare contact data in the format the provider expects (LinkedIn URL, name + domain, etc.) 2. Submit contacts in batches according to the provider's rate limits 3. Handle async responses if the provider uses polling 4. Collect results: emails, phone numbers, verification status 5. Track matched vs. unmatched contacts

If the user wants a waterfall (two providers), run the first provider, collect misses, then run misses through the second.

Step 4: Deduplicate and clean

Deduplicate by email. Filter out:

• Entries with no email
• Results where the provider marks verification as invalid

Step 5: Output contact CSV

Save enriched contacts to claude-code-gtm/csv/input/{campaign}/contacts.csv with columns:

• first_name, last_name, email, email_verified, job_title, company_name, domain, linkedin_url, phone, location, source

Step 6: Review with user

Present summary:

Enrichment Results:
- Contacts submitted: N
- Emails found: N (X% hit rate)
- Emails verified: N
- Phones found: N
- No match: N
- Provider: [chosen provider]

Show a sample of 10 contacts for spot-checking:

Ask:

• "Hit rate look acceptable? (>60% is good, >80% is great)"
• "Want to run the misses through another provider?"
• "Ready to proceed to email-generation?"

API References

Pre-configured provider docs in references/ directory. For other providers, docs are fetched during Step 0.

Fullenrich API Reference

Waterfall contact enrichment — tries multiple data providers to maximize hit rate on emails and phones.

Base URL: https://api.fullenrich.com/api/v1 Auth: Authorization: Bearer YOUR_API_KEY API Key: https://app.fullenrich.com/app/api

Credit Costs

Endpoints

Check Credits

GET /account/credits

Response: { "credits": 1234 }

Verify API Key

GET /account/keys/verify

Bulk Enrich Contacts (async)

POST /contact/enrich/bulk

Batch size: Up to 100 contacts per request.

Request body:

{
  "contacts": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "domain": "acme.com",
      "linkedin_url": "https://www.linkedin.com/in/janedoe/"
    }
  ],
  "webhook_url": "https://your-server.com/webhook",
  "webhook_events": ["contact_finished"]
}

Required fields (at least one combo):

• first_name + last_name + domain (or company_name)
• linkedin_url (improves accuracy 5-20% for emails, 10-60% for phones)

Optional fields:

• company_name — company name (use domain when possible for better accuracy)
• webhook_url — URL for async result delivery (recommended over polling)
• webhook_events — ["contact_finished"] for per-contact notifications
• silentFail — query param, true to skip invalid contacts quietly

Response:

{
  "enrichment_id": "uuid",
  "status": "processing",
  "total_contacts": 5
}

Get Enrichment Results

GET /contact/enrich/bulk/{enrichment_id}

Response:

{
  "enrichment_id": "uuid",
  "status": "completed",
  "results": [
    {
      "input": { "first_name": "Jane", "last_name": "Doe", "domain": "acme.com" },
      "work_email": {
        "email": "jane.doe@acme.com",
        "verification_status": "DELIVERABLE"
      },
      "personal_email": {
        "email": "jane@gmail.com",
        "verification_status": "DELIVERABLE"
      },
      "mobile_phone": {
        "number": "+14155551234",
        "region": "US"
      },
      "profile": {
        "full_name": "Jane Doe",
        "title": "VP of Sales",
        "location": "San Francisco, CA",
        "linkedin_url": "https://linkedin.com/in/janedoe",
        "employment_history": [...],
        "education": [...]
      },
      "company": {
        "name": "Acme Corp",
        "domain": "acme.com",
        "industry": "Software",
        "employee_count": 250
      }
    }
  ]
}

Email verification statuses:

Reverse Email Lookup (async)

POST /contact/reverse/email/bulk

{
  "emails": ["jane@acme.com", "john@example.com"],
  "webhook_url": "https://your-server.com/webhook"
}

Cost: 1 credit per match. Works with work and personal emails.

GET /contact/reverse/email/bulk/{enrichment_id}

People Search (sync)

POST /people/search

{
  "filters": {
    "job_title": ["VP of Sales", "Head of Sales"],
    "seniority": ["VP", "Director"],
    "location": ["United States"],
    "company_size": ["51-200", "201-500"],
    "industry": ["Software"]
  },
  "page": 1
}

Cost: 0.25 credits per result returned. Synchronous response.

Company Search (sync)

POST /company/search

Similar filter structure to people search but with company-level filters.

Rate Limits

• 60 API calls per minute (default, can be increased on request)
• 100 contacts per bulk enrichment request
• 100 concurrent enrichments in queue
• 100 concurrent reverse lookups in queue
• Search API is synchronous (no queue)
• Effective throughput: ~6,000 contacts/minute

Processing Time

• Average: 30-90 seconds per contact
• Varies by data availability and waterfall depth
• Use webhooks (recommended) instead of polling for results

Webhook Integration (recommended)

Set webhook_url in bulk requests. Fullenrich will POST results as they complete:

• Per-contact: webhook_events: ["contact_finished"]
• Retries: up to 5 times on delivery failure
• Verify delivery using a test endpoint

Test Contact (0 credits)

{
  "first_name": "Grégoire",
  "last_name": "Démogé",
  "domain": "fullenrich.com",
  "linkedin_url": "https://www.linkedin.com/in/demoge/"
}

Data Retention

Results retained for 3 months (GDPR). Re-enrichment within window costs 0 credits.

Prospeo API Reference

Person and company enrichment with 200M+ contact database and 30+ search filters.

Base URL: https://api.prospeo.io Auth header: X-KEY: your_api_key Content-Type: application/json Method: All endpoints use POST API Key: https://app.prospeo.io/api

Credit Costs

Rate Limits

Tier-based. Check response headers:

• x-daily-request-left — remaining daily requests
• x-minute-request-left — remaining per-minute requests
• x-second-rate-limit — per-second limit
• x-daily-reset-seconds — seconds until daily reset
• x-minute-reset-seconds — seconds until minute reset

Returns 429 when exceeded.

Endpoints

Search Person

POST /search-person

Search 200M+ contacts with 30+ filters. Returns person + company data but no email/mobile — use Enrich Person for that.

Request:

{
  "filters": {
    "job_title": {
      "v": ["VP of Sales", "Head of Sales"],
      "condition": "or"
    },
    "seniority": {
      "v": ["VP", "Director", "C-Suite"],
      "condition": "or"
    },
    "department": {
      "v": ["Sales"],
      "condition": "or"
    },
    "person_location": {
      "v": ["United States"],
      "condition": "or"
    },
    "industry": {
      "v": ["Software", "Information Technology"],
      "condition": "or"
    },
    "employee_range": {
      "v": ["51-200", "201-500"],
      "condition": "or"
    },
    "company_website": {
      "v": ["acme.com", "example.com"],
      "condition": "or"
    }
  },
  "page": 1
}

Available filters:

All filters use "condition": "or" (match any) or "condition": "and" (match all) within the same filter field.

Response:

{
  "error": false,
  "results": [
    {
      "person": {
        "id": "person-uuid",
        "first_name": "Jane",
        "last_name": "Doe",
        "full_name": "Jane Doe",
        "linkedin_url": "https://linkedin.com/in/janedoe",
        "title": "VP of Sales",
        "seniority": "VP",
        "department": "Sales",
        "location": "San Francisco, CA, US",
        "skills": ["B2B Sales", "SaaS", "Revenue Operations"]
      },
      "company": {
        "name": "Acme Corp",
        "website": "acme.com",
        "linkedin_url": "https://linkedin.com/company/acme",
        "industry": "Software",
        "headcount": 250,
        "founded_year": 2018,
        "location": "San Francisco, CA, US"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_page": 40,
    "total_count": 1000
  }
}

Pagination: 25 results per page, max 1000 pages (25,000 results).

Enrich Person

POST /enrich-person

Get verified email and optional mobile for a specific person.

Request:

{
  "data": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company_website": "acme.com"
  },
  "only_verified_email": true,
  "enrich_mobile": true,
  "only_verified_mobile": false
}

Required fields (at least one combo):

• first_name + last_name + (company_website | company_name | company_linkedin_url)
• full_name + company info
• linkedin_url alone
• email alone
• person_id (from Search Person results)

Optional params:

• only_verified_email (bool) — only return if email is verified
• enrich_mobile (bool) — include mobile lookup (costs 10 credits instead of 1)
• only_verified_mobile (bool) — only return if mobile is verified

Response:

{
  "error": false,
  "free_enrichment": false,
  "person": {
    "first_name": "Jane",
    "last_name": "Doe",
    "full_name": "Jane Doe",
    "linkedin_url": "https://linkedin.com/in/janedoe",
    "title": "VP of Sales",
    "email": "jane.doe@acme.com",
    "email_verified": true,
    "mobile": "+14155551234",
    "mobile_verified": true,
    "location": "San Francisco, CA, US",
    "skills": ["B2B Sales", "SaaS"]
  },
  "company": {
    "name": "Acme Corp",
    "website": "acme.com",
    "industry": "Software",
    "headcount": 250
  }
}

Error codes: NO_MATCH, INVALID_DATAPOINTS, INSUFFICIENT_CREDITS, INVALID_API_KEY, RATE_LIMITED

Bulk Enrich Person

POST /bulk-enrich-person

Enrich up to 50 records at once. Same matching rules as single enrich.

Request:

{
  "only_verified_email": true,
  "enrich_mobile": false,
  "only_verified_mobile": false,
  "data": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "company_website": "acme.com"
    },
    {
      "linkedin_url": "https://linkedin.com/in/johndoe"
    }
  ]
}

Batch size: Max 50 records per request.

Response:

{
  "error": false,
  "total_cost": 5,
  "matched": [
    {
      "person": { ... },
      "company": { ... }
    }
  ],
  "not_matched": [
    { "first_name": "Unknown", "last_name": "Person", "company_website": "none.com" }
  ],
  "invalid_datapoints": []
}

Search Suggestions

POST /search-suggestions

Get exact filter values for job titles, locations, etc. Use before Search Person to get precise values.

Enrich Company

POST /enrich-company

Get verified company data including funding and technology details.

Search Company

POST /search-company

Search 30M+ company records.

Removed Endpoints (removed March 1, 2026)

These endpoints have been removed. Use the replacements listed:

• ~~Email Finder~~ → use Enrich Person
• ~~Mobile Finder~~ → use Enrich Person with enrich_mobile: true
• ~~Email Verifier~~ → use Enrich Person with only_verified_email: true
• ~~Domain Search~~ → use Search Person with company_website filter
• ~~Social URL Enrichment~~ → use Enrich Person with linkedin_url