agentleFS
vivekkhimanivivekkhimani/gtm-tools-template/.agents/skills/gtm-people-enrichment/SKILL.md

gtm-pipeline:people-enrichment

Skill1 starsChanged 5 months agoMITView on GitHub

Enrich contacts with work email, phone number, and/or LinkedIn URL. Use when you have a contact list that needs enrichment before outreach. Email waterfall (FullEnrich → Pipe0), phone (BetterContact → FullEnrich). Enforces demo mode (email only, no phone). Also triggers on "enrich contacts", "find emails for", "get phone numbers for".

  • Reads credentials

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 8 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When invoked from the demo flow: email only, skip all phone providers entirely.

    line 31
  2. Distinctive:

    Check what fields are available (LinkedIn URL, domain, name, company)

    line 69
  3. Distinctive:

    Run chosen provider on 5–10 contacts in production

    line 75
  4. Distinctive:

    Check hit rate — if below 10%, investigate before proceeding

    line 77
  5. Distinctive:

    Run fallback provider on misses only

    line 96
  6. Very specific:

    Add email_source and phone_source columns for traceability

    line 101
  7. Distinctive:

    Use v2 (not v1)

    line 158
  8. Very specific:

    If credits run out mid-batch: status = "CREDITS_INSUFFICIENT", partial results returned

    line 163
  9. Distinctive:

    After enrichment, filter out stale/personal emails:

    line 213
  10. Distinctive:

    All original columns preserved.

    line 339
  11. Very specific:

    Prefer contact_info.most_probable_phone.number (typically mobile) over phones[0].number (can be landline).

    line 361

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

People Enrichment

Enrich contacts with work email, phone number, and/or LinkedIn URL. Returns an updated CSV.

Read .agents/skills/_shared/conventions.md before executing.


When to Use

  • You have a contact list and need emails and/or phone numbers
  • Contacts from people-search need enrichment before outreach
  • A user-provided CSV has names + companies but missing contact info

Inputs

InputRequiredSource
Contact CSVYesPeople Search output or user-provided
LinkedIn profile URLsRecommendedIn CSV or from People Search
Company domainsRecommendedIn CSV
Enrichment typeYesemail, phone, or both

Demo Mode

When invoked from the demo flow: email only, skip all phone providers entirely.


Provider Selection

Email

Ask the user which provider to use. Default recommendation:

PriorityProviderHit RateCostSpeedNotes
1stFullEnrich v280% (SA), 83% (DACH)0.8 cr/contactinstantClear winner
2ndPipe0 waterfall60% (SA), 83% (DACH)1.0–3.5 cr/contact~3 min/20 contactsSolid backup
3rdBetterContact (email-only)~60% test / 14% production SA0.35 cr/contact30–90 minNot recommended — slow, unreliable production

Recommended flow: FullEnrich first → Pipe0 for FE misses → skip BC for email.

Phone

Skip entirely in demo mode.

PriorityProviderHit RateCostSpeedNotes
1stFullEnrich v2~60% DACH~0.8 cr/contactinstantGood DACH coverage. Prefer most_probable_phone.number over phones[0] (phones[0] can be landline, most_probable is mobile)
2ndPipe0 phone waterfall~92% DACH (n=74) · 0% SA2–7 cr/contact~30s/batchResponse field: mobile (not phone). Works reliably as FE fallback — on 7 FE contacts missing phones, recovered 5 (71%). Also strong as primary when contacts come from Pipe0 search (68/74 = 92%)
3rdBetterContact13–74% (~22% SA, ~53% DACH)~1–2 cr/contact5–10+ min for small batchesUnreliable speed — took 10+ min for 2 contacts in DACH test. Retest before production

LinkedIn URL (when missing)

  • Pipe0 people:profileurl:name@1 — 0.60 cr/person, needs name + company_name + location_hint
  • PhantomBuster Profile Scraper (config key: PB_AGENT_PROFILE) — scrape full profile data from existing LinkedIn URL; use /phantombuster skill with phantom name "LinkedIn Profile Scraper" and CSV path. See _shared/phantombuster.md.

Execution Protocol

1. Assess Input Data

  • Check what fields are available (LinkedIn URL, domain, name, company)
  • Determine which enrichment types are needed
  • Estimate credit cost: n_contacts × max_cost_per_record
  • Confirm credit balance with user before proceeding

2. Test Batch (5–10 contacts)

  • Run chosen provider on 5–10 contacts in production
  • Inspect every result: email validity status, phone format, match accuracy
  • Check hit rate — if below 10%, investigate before proceeding

3. Review with User

  • Present test results with hit rate, status breakdown, sample data
  • Confirm provider choice and credit spend for full batch
  • Get approval

4. Full Batch

  • Split into chunks of max 100 contacts per request (all providers)
  • Save request/task IDs immediately
  • Poll with appropriate timeouts:
    • FE: 15s interval, 600s timeout (usually instant)
    • Pipe0: 30s interval, 600s timeout (≤100 contacts)
    • BC phone: 30s interval, 900s timeout
    • BC email: 60s interval, 3600s timeout
  • Save results incrementally after each batch

5. Fallback Pass

  • Identify contacts with missing email/phone after primary provider
  • Run fallback provider on misses only
  • Merge results

6. Final Output

  • Merge all provider results into single CSV
  • Add email_source and phone_source columns for traceability
  • Flag email status (deliverable, catch_all, undeliverable)
  • Write to csv/output/contacts_enriched.csv

Provider 1: FullEnrich v2 (Email + Phone)

Endpoint: POST https://app.fullenrich.com/api/v2/contact/enrich/bulk Auth: Authorization: Bearer $FULLENRICH_API_KEY

Submit (max 100 contacts/batch)

{
  "name": "My enrichment job",
  "data": [
    {
      "firstname": "Jane",
      "lastname": "Doe",
      "domain": "example.com",
      "linkedin_url": "https://www.linkedin.com/in/janedoe",
      "enrich_fields": ["contact.emails"],
      "custom": {"row_id": "0"}
    }
  ]
}

For phone: "enrich_fields": ["contact.phones"] or both: ["contact.emails", "contact.phones"]

Poll

GET https://app.fullenrich.com/api/v2/contact/enrich/bulk/{enrichment_id}

Done when: response["status"] == "FINISHED" Speed: usually instant — often finished before first poll. Use 15s interval, 600s timeout.

Parse

for entry in result.get("data", []):
    row_id = str(entry.get("custom", {}).get("row_id", ""))
    ci = entry.get("contact_info", {})
    # Email
    best = ci.get("most_probable_work_email", {})
    email = best.get("email", "") or ""
    if not email:
        for e in ci.get("work_emails", []):
            if e.get("email"):
                email = e["email"]; break
    email_status = best.get("status", "")  # DELIVERABLE / HIGH_PROBABILITY / CATCH_ALL
    # Phone
    phone_list = ci.get("phones", [])
    phone = phone_list[0].get("number", "") if phone_list else ""

Key Notes

  • Base URL is app.fullenrich.com (NOT api.fullenrich.com)
  • Use v2 (not v1)
  • Max 100 contacts per batch
  • Submit response key is enrichment_id (UUID)
  • Email: contact_info.most_probable_work_email.email
  • Phone: contact_info.phones[0].number
  • If credits run out mid-batch: status = "CREDITS_INSUFFICIENT", partial results returned
  • Email status values: DELIVERABLE, HIGH_PROBABILITY, CATCH_ALL

Cost

~0.8 credits/contact

Docs

https://docs.fullenrich.com


Provider 2: Pipe0 Email Waterfall

Pipe ID: people:workemail:profileurl:waterfall@1 Auth: Authorization: Bearer $PIPE0_API_KEY Use curl — Python requests blocked by Cloudflare.

Submit

{
  "config": {"environment": "production"},
  "pipes": [{"pipe_id": "people:workemail:profileurl:waterfall@1"}],
  "input": [
    {"id": "1", "profile_url": "https://linkedin.com/in/janedoe"}
  ]
}

Key Notes

  • Submit response key is id (not task_id) — use this value for polling: GET /pipes/check/{id}
  • email_validation_status field is also returned alongside work_email in each record
  • Email quality: ~15–25% of hits may be stale (old employer email) for EU audiences. Waterfall picks up the most recent known email regardless of current role. Always post-filter: remove personal domains (gmail, yahoo, etc.) and cross-check email domain against current company. In EU SME test: 37/43 raw hits, 30/43 valid after filtering 7 stale/personal.

Poll

GET https://api.pipe0.com/v1/pipes/check/{id}

Done when: status == "completed". Use 30s interval, 600s timeout (~3 min for 43 contacts). Keep batches ≤100 contacts.

Parse

records = result.get("records", {})
for rid, rec in records.items():
    fields = rec.get("fields", {})
    email  = (fields.get("work_email", {}) or {}).get("value", "") or ""
    status = (fields.get("email_validation_status", {}) or {}).get("value", "") or ""
    # work_email.value is a plain string, NOT nested

Post-filtering (Recommended)

After enrichment, filter out stale/personal emails:

PERSONAL_DOMAINS = {'gmail.com','yahoo.com','hotmail.com','outlook.com','icloud.com'}
df['email'] = df['email'].apply(
    lambda e: "" if (e and e.split('@')[-1].lower() in PERSONAL_DOMAINS) else e
)
# Also manually flag emails where domain doesn't match current company

Waterfall Providers & Cost

ProviderCost
HunterMail1.00 cr
LeadMagic2.00 cr
FindyMail2.00 cr
Crustdata3.50 cr
Stops at first hit. Total: 1.00–3.50 cr/contact.

Provider 3: BetterContact (Email or Phone)

Endpoint: POST https://app.bettercontact.rocks/api/v2/async Auth: X-API-KEY: $BETTERCONTACT_API_KEY

Submit (max 100 contacts/batch)

{
  "enrich_email_address": false,
  "enrich_phone_number": true,
  "data": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "company_domain": "example.com",
      "linkedin_url": "https://www.linkedin.com/in/janedoe",
      "custom_fields": {"row_id": "0"}
    }
  ]
}

Poll

GET https://app.bettercontact.rocks/api/v2/async/{request_id}

Done when: response["status"] == "terminated" (NOT "completed")

  • Phone only: ~3–5 min/100 contacts. Use 900s timeout.
  • Email only or both: 30–90 min. Use 3600s timeout.
  • on hold = credits exhausted, batch paused — no cancel endpoint.

Parse

for entry in result.get("data", []):
    cf = entry.get("custom_fields", [])  # ARRAY, not dict
    row_id = next((f["value"] for f in cf if f.get("name") == "row_id"), "")
    phone = entry.get("contact_phone_number") or ""
    email = entry.get("contact_email_address") or ""
    email_status = entry.get("contact_email_address_status") or ""

Key Notes

  • Base URL: app.bettercontact.rocks (not api.)
  • Max 100 contacts per batch
  • Submit response key: id (not task_id or request_id)
  • status for completion: "terminated", not "completed"
  • custom_fields sent as object {"key": "val"}, returned as array: [{"name": "key", "value": "val", "position": 0}]
  • Email field: contact_email_address, status: contact_email_address_status
  • Phone field: contact_phone_number
  • enriched: False entries can still have email values — these are low-confidence (catch_all_not_safe). Count but flag.
  • Summary total field excludes not_found — use len(data) for verification

Cost

  • Email only: ~0.35 cr/contact
  • Phone only: ~1–2 cr/contact
  • Can spike to 7+ cr/contact for enterprise audiences (complex email infra)

Docs

https://doc.bettercontact.rocks


Provider 4: Pipe0 LinkedIn URL (When Missing)

Pipe ID: people:profileurl:name@1

Request

{
  "config": {"environment": "production"},
  "pipes": [{"pipe_id": "people:profileurl:name@1"}],
  "input": [
    {"id": "1", "name": "John Smith", "company_name": "Example Inc", "location_hint": "United States"}
  ]
}

Cost

0.60 credits/operation


Provider 5: Pipe0 Phone Pipes

Pipe IDs:

  • people:phone:profile:waterfall@1 — input: profile_url (LinkedIn URL)
  • people:phone:workemail:waterfall@1 — input: work_email

Cost

2.00–7.00 credits/operation

Known Coverage

  • DACH: ~92% hit rate (n=74), April 2026 DACH e-commerce SME run — response field is mobile, not phone
  • SA: 0% hit rate observed — skip for SA audiences
  • Solid as both primary (when contacts come from Pipe0 search → no FE phone available) and FE-fallback (71% recovery on FE contacts missing phones, n=7). Use FE first if the contact already went through FE search/enrich (you've paid for it); use Pipe0 waterfall on the remainder.

Output

Updated CSV at csv/output/contacts_enriched.csv with added columns:

email, email_status, email_source,
phone, phone_source

All original columns preserved.


Troubleshooting

Pipe0: Task processing timeout

Batch too large. Keep batches ≤100 contacts. Re-poll task_id — partial results may be in records.

Pipe0: CreditBalanceInsufficient

Batch fails but credits for provider responses are consumed. Top up, save task_id, do NOT resubmit. New batch for failed records only.

BetterContact: Job never terminates

Timeout too short. Phone: 900s min. Email: 3600s min.

BetterContact: custom_fields parse error

custom_fields is an array [{"name": "row_id", "value": "0"}], not a dict.

FullEnrich: 404 on results

Wrong path. Correct: https://app.fullenrich.com/api/v2/contact/enrich/bulk/{enrichment_id}

FullEnrich: Phone field empty

Prefer contact_info.most_probable_phone.number (typically mobile) over phones[0].number (can be landline). If most_probable_phone is absent, fall back to phones[0]. If both empty, fall back to Pipe0 people:phone:profile:waterfall@1 on the LinkedIn URL.


What's Missing (To Document)

  • Pipe0 phone pipe coverage by geography (currently only DACH/SA tested)
  • FullEnrich v2 phone hit rates by geography
  • BetterContact email-only production hit rates outside SA

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.