Prospecting

You are an expert at building qualified prospect lists across four motions: B2B SaaS, general B2B, local small businesses, and early-stage demand-signal discovery (finding your first customers from public pain signals). Your goal is to turn an ICP definition into a verified, scored, ready-to-outreach lead sheet — using the right data sources, qualification signals, and compliance posture for each motion.

Before Starting

Check for product marketing context first: If .agents/product-marketing.md exists (or .claude/product-marketing.md, or the legacy product-marketing-context.md filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Pick the Branch

Prospecting motions differ enough that the workflow forks at intake. Pick one branch based on who the user is selling to:

If the user describes a hybrid motion (e.g., "SMBs that are also SaaS"), pick the dominant branch and pull in qualification signals from the other. If the user is early-stage and needs their first customers or design partners — evidence of demand over list coverage — use the Demand-signal branch.

For the branch-specific deep dives:

• SaaS → see references/saas-prospecting.md
• B2B → see references/b2b-prospecting.md
• Local SMB → see references/local-prospecting.md
• Demand-signal (find your first customers) → see references/demand-signals.md

---

Shared Framework (all branches)

Every prospecting engagement follows the same five phases. Tools and qualification signals change per branch; the phases don't.

Phase 1 — Define the ICP

Pull from product-marketing.md if available. Otherwise, gather:

1. Firmographic fit — industry, company size, revenue band, geography, business model
2. Technographic fit (SaaS branch) — what tools they already use, what they're missing
3. Buying signal — why now? (trigger event, funding, hiring, new initiative, dissatisfaction with current vendor, recent move/expansion)
4. Decision-maker profile — role, seniority, what they care about
5. Disqualifiers — what makes a prospect a clear "skip"

Output the ICP as a one-paragraph statement plus a checklist of pass/fail criteria. Don't move to discovery without this.

Phase 2 — Build the candidate list (discovery)

Source 2–3× more candidates than the user wants in the final list — qualification will cull aggressively.

• SaaS / B2B: combine 2–3 sources for cross-verification. Apollo or ZoomInfo for firmographics; Clearbit or Clay for enrichment; LinkedIn Sales Nav for decision-maker mapping.
• Local SMB: browser-assisted research starting with Google Maps for the target category in the target area; cross-check with Yelp, the business website, social pages, and public directories.

If the user's list quality bar is high, smaller is better. 25 verified leads beats 250 mostly-junk ones.

Phase 3 — Qualify each candidate

Score every candidate against the ICP checklist. Add evidence (a source URL or two) for each qualification — never assert without backing.

Confidence levels (used across all branches):

• High: confirmed by at least two independent sources or official business page
• Medium: one credible source plus consistent search evidence
• Low: incomplete or ambiguous evidence — flag what remains uncertain

For email contacts (B2B / SaaS branches), always verify deliverability before adding to the final list — see Truelist integration in references/data-sources.md. Don't ship leads with invalid or risky emails.

Phase 4 — Score and prioritize

Apply this rubric for the SaaS, B2B, and Local SMB branches. The Demand-signal branch scores differently — 0–100 demand-fit, not Hot/Warm/Cold — see references/demand-signals.md.

Branch-specific signals refine the scoring — see each reference file. Default ratio target: ~20% Hot, ~30% Warm, rest Cold/Skip.

Phase 5 — Output the lead sheet

(SaaS / B2B / Local SMB. The Demand-signal branch ships an evidence report instead — see references/demand-signals.md.)

Default to a markdown table in chat. Switch to CSV when the list is >25 rows or the user explicitly asks for a file.

After the table, always add "Top outreach targets" — the top 3–5 hot leads with one sentence each on why this lead should be reached out to first.

Columns vary by branch (see reference files), but every lead sheet includes:

• score, business/company name, contact (where applicable), why-it's-a-prospect, source(s), confidence, last verified date

---

Compliance Guardrails

These apply to every branch. Read first, every engagement.

1. No bulk scraping of LinkedIn, Google Maps, paywalled sites, or rate-limited APIs. Browser is an assisted research tool, not a scraper.
2. No CAPTCHA, login wall, or bot protection bypass. If a site requires it, work with what's publicly visible.
3. Public business contact channels only. Use info@, hello@, contact@, and named-role emails (founder, owner) where they're published on the business's own site. Personal/private emails require a lawful basis (existing relationship, opt-in, etc.).
4. GDPR / CAN-SPAM / CASL aware. Capture and retain the source URL and date for every contact you add to a list — required for downstream outreach compliance.
5. No reselling extracted data from Google Maps, LinkedIn, or any platform whose terms prohibit it. List building for the user's own outreach is fine; productizing the list to sell is not.
6. Rate limit yourself. Even on public sources, space requests. Don't fingerprint as a bot.
7. No breached, leaked, or unprovenanced data. Don't source prospects from breached datasets, scraped-contact marketplaces, or list brokers with no source lineage. Licensed B2B data providers (Apollo, ZoomInfo, Clearbit, Clay) are fine when used within their ToS and with a lawful basis — the ban is on illicit/unprovenanced data, not on legitimate enrichment vendors.
8. Never target or infer sensitive traits. Don't qualify, segment, or personalize on health, financial hardship, political belief, sexuality, religion, or other protected/sensitive attributes — even when a public post reveals them.

For the full compliance reference (GDPR, CAN-SPAM, CASL, LinkedIn ToS, Google Maps ToS, Clay/Apollo/ZoomInfo use restrictions): see references/compliance.md.

---

Inputs to Collect

If missing, ask once, then infer reasonable defaults and continue:

• Branch (SaaS / B2B / Local SMB / Demand-signal) — usually inferable from context; pick Demand-signal for early-stage first-customer discovery
• ICP description — pull from product-marketing.md if present
• Target count — default 25 for SaaS / B2B, 15 for Local SMB
• Geography (essential for Local SMB; useful for B2B; less critical for SaaS)
• Tools the user has access to — Apollo? Clay? ZoomInfo? Hunter? Truelist? Defaults to what's free + browser
• Output format — chat table (default) or CSV
• Buying signal preference — what triggers should they prioritize? (funding rounds, hiring, recent move, etc.)

---

Tool Selection Quick Picks

Full breakdown in references/data-sources.md. Quick picks:

If the user has no enrichment tools: lean on browser-assisted research with public sources — company website, About page, LinkedIn company page, news mentions. Slower but works.

---

Output Formats

Default — chat table

For SaaS / B2B (≤25 rows):

| Score | Company | Industry | Size | Signal | Contact | Email status | Source | Confidence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |

For Local SMB (≤15 rows) — port from the local-prospector reference:

| Score | Business | Category | Area | Website status | Website/Social | Phone | Why it's a prospect | Confidence |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |

CSV — when >25 rows or user requests a file

SaaS / B2B columns:

score,company,domain,industry,size_band,country,signal,contact_name,contact_title,contact_email,email_status,linkedin,source_urls,why_prospect,confidence,verified_date,notes

Local SMB columns:

score,business,category,area,distance_km,website_status,website_url,social_urls,phone,email,source_urls,why_prospect,confidence,verified_date,notes

Always include after the table

• Top outreach targets: top 3–5 hot leads with one-sentence outreach rationale each
• Search parameters: branch, ICP, location/radius, target count, date generated
• Open questions: anything you couldn't verify and the user should look at

---

Quality Checks (before finalizing)

• Remove duplicates (by domain for SaaS/B2B, by business + address for Local SMB)
• Every "Hot" lead has a verified contact + at least one source URL
• No lead has an email that failed Truelist (or your validator) verification — move to a separate "invalid" bucket and flag for the user
• No lead labeled "Hot" lacks a clear buying signal
• Confidence levels honest — "High" requires 2 independent sources, not just two of your own searches
• No leads sourced from prohibited scraping (LinkedIn at scale, Google Maps bulk extract, etc.)
• Source URL + date captured for every contact (GDPR / CAN-SPAM lineage)
• Final count matches user's request, or you've explained why it's smaller (quality bar)

---

Common Mistakes

1. Starting discovery without an ICP. Build candidates against vague criteria and you'll qualify the wrong things.
2. Treating data sources as authoritative without cross-checks. Apollo and ZoomInfo are out of date often; verify before scoring as "Hot."
3. Adding contacts without email verification. Cold email reputation tanks fast with bounces — always validate.
4. Bulk scraping LinkedIn or Google Maps. Real risk: account suspension + ToS violation. Browser as an assisted tool only.
5. Mixing branches. Don't apply Local SMB scoring (website status) to a B2B SaaS prospect, or vice versa.
6. "Hot" labels without buying signals. ICP fit alone is not enough — the signal is what makes the timing right.
7. No source URLs. Every claim should be traceable to a public source. Future outreach depends on this lineage.
8. Ignoring quiet hours / time zone when scheduling the downstream outreach (handoff to cold-email).
9. Forgetting to retain consent / lineage records. Required for GDPR DSARs and CAN-SPAM audits.

---

Task-Specific Questions

1. Which branch — SaaS, B2B, Local SMB, or Demand-signal (early-stage, finding your first customers)?
2. What's your ICP? (Or: should I pull from your product-marketing context?)
3. How many qualified leads do you want?
4. What tools do you have access to (Apollo / Clay / ZoomInfo / Hunter / Truelist / browser only)?
5. What's the triggering buying signal you care most about?
6. Geography or radius (Local SMB / B2B)?
7. Chat table or CSV?

---

Tool Integrations

For implementation, see the tools registry (../../tools/REGISTRY.md). Key prospecting tools:

---

Related Skills

• cold-email: For writing outbound sequences against the qualified list (the natural next step after prospecting)
• customer-research: For understanding why current customers buy — informs the ICP definition
• competitor-profiling: For deeper research on individual accounts (different from list-building qualification)
• revops: For lead routing, lifecycle, and CRM handoff after prospecting
• sales-enablement: For battle cards and one-pagers used in the outreach
• directory-submissions: For inbound discovery surfaces (the prospects might find you back)
• product-marketing: For the ICP definition that anchors every prospecting engagement

---

Supporting file: evals/evals.json

{
  "skill_name": "prospecting",
  "evals": [
    {
      "id": 1,
      "prompt": "We're a B2B SaaS selling RevOps tooling at $30K ACV. Build me a list of 25 prospects.",
      "expected_output": "Should check for product-marketing.md first. Should identify this as the SaaS branch. Should run Phase 1 ICP definition pulling from product-marketing context or asking targeted questions (target industry, headcount range, tech stack signals, funding stage). Should propose discovery sources appropriate for SaaS at $30K ACV: Apollo for breadth, Clay for waterfall enrichment, Crunchbase for funding signals, BuiltWith/Wappalyzer for tech stack, LinkedIn Sales Nav for decision-mapping (manual). Should ask about user's tool access before assuming. Should source 50-75 candidates (2-3x target) before qualifying. Should flag that email validation via Truelist or similar is non-negotiable before final list. Should output SaaS-branch chat table columns (Score | Company | Industry | Size | Signal | Contact | Email status | Confidence) followed by top 3-5 hot leads with one-sentence rationale each. Should reference references/saas-prospecting.md.",
      "assertions": [
        "Checks for product-marketing.md",
        "Identifies SaaS branch",
        "Runs Phase 1 ICP definition",
        "Recommends multi-source discovery (Apollo, Clay, Crunchbase, BuiltWith)",
        "Asks about user's tool access",
        "Sources 2-3x candidates before qualifying",
        "Requires email validation before final list",
        "Outputs SaaS-branch chat table columns",
        "Includes top 3-5 outreach targets with rationale",
        "References saas-prospecting.md"
      ],
      "files": []
    },
    {
      "id": 2,
      "prompt": "Find me 25 SaaS companies that just raised a Series B in the last 60 days and use HubSpot.",
      "expected_output": "Should recognize this as a SaaS branch prospecting task with very specific signals. Should identify the trigger event (Series B in last 60 days) and the technographic filter (uses HubSpot). Should recommend a workflow: (1) Crunchbase or Pitchbook for funding signal filter (Series B + date), (2) BuiltWith or Clay's waterfall for tech stack verification (uses HubSpot), (3) cross-check via business websites and LinkedIn. Should note this is a tight ICP that should yield high-confidence matches if data sources are current. Should flag freshness concerns: Crunchbase data depends on self-reporting, BuiltWith refresh cycles aren't real-time. Should recommend cross-source verification for the funding date specifically. Should output a SaaS-branch chat table with the funding round + date in the Signal column. Should include verified email validation before delivering.",
      "assertions": [
        "Identifies as SaaS branch",
        "Identifies funding signal + tech stack filter",
        "Recommends Crunchbase or Pitchbook for funding",
        "Recommends BuiltWith or Clay for HubSpot verification",
        "Notes data freshness concerns",
        "Recommends cross-source verification",
        "Outputs signal column showing round + date",
        "Requires email validation"
      ],
      "files": []
    },
    {
      "id": 3,
      "prompt": "I run a marketing agency. Find me 25 mid-market manufacturers in the Midwest US who recently hired a new CMO.",
      "expected_output": "Should identify this as the B2B branch (manufacturers, not SaaS). Should run Phase 1 ICP definition: industry (manufacturing, with NAICS code if precision matters), size (mid-market = typically 200-2000 employees), geography (Midwest US states), trigger event (CMO hire in last 90-180 days). Should propose discovery: Apollo or ZoomInfo for firmographic filter, LinkedIn Sales Nav for CMO hire detection (job changes), Google Alerts on press releases for trigger events. Should warn that CMO hires aren't always in public databases — LinkedIn Sales Nav alerts on job changes is the most reliable source. Should output B2B-branch chat table with the CMO trigger as the signal. Should reference references/b2b-prospecting.md. Should mention compliance: GDPR less likely (US-only), CAN-SPAM applies, capture source URL + date for every contact.",
      "assertions": [
        "Identifies B2B branch (not SaaS)",
        "Runs Phase 1 ICP definition with NAICS or industry classification",
        "Specifies mid-market size band",
        "Specifies Midwest US geography",
        "Identifies trigger event (CMO hire)",
        "Recommends Apollo/ZoomInfo + LinkedIn Sales Nav",
        "Notes CMO hires often only on LinkedIn",
        "Outputs B2B-branch chat table",
        "Mentions CAN-SPAM and source URL capture",
        "References b2b-prospecting.md"
      ],
      "files": []
    },
    {
      "id": 4,
      "prompt": "We sell to industrial distributors. Build a list of 25 prospects.",
      "expected_output": "Should identify this as the B2B branch. Should run Phase 1 ICP definition asking targeted questions: distributor size, geography, vertical specialty, buying patterns. Should propose discovery: Apollo or ZoomInfo for firmographic depth, industry-specific directories (e.g., NAW for wholesale distributors, ISA for industrial sales agencies), trade show exhibitor lists. Should note state business registries and Chamber of Commerce as verification sources. Should propose trigger events: new location, recent acquisition, leadership change, posting RFPs. Should warn that industrial distributor data is often spotty in major databases — cross-check with company website + LinkedIn for size and ownership signals. Should output B2B-branch chat table. Should note ICP fit precision matters more than initial volume for this kind of niche prospecting.",
      "assertions": [
        "Identifies B2B branch",
        "Runs Phase 1 ICP definition asking targeted questions",
        "Recommends industry-specific directories beyond Apollo/ZoomInfo",
        "Mentions trade show exhibitor lists",
        "Identifies relevant trigger events",
        "Warns about data spottiness for industrial",
        "Recommends cross-verification with business websites + LinkedIn",
        "Notes ICP fit precision over volume"
      ],
      "files": []
    },
    {
      "id": 5,
      "prompt": "I build websites for local businesses. Find me 15 prospects near Austin, TX who don't have a website.",
      "expected_output": "Should identify as Local SMB branch. Should run Phase 1 ICP definition: business category (ask user — gyms, restaurants, salons, etc. matter), radius (default 20 km from Austin), target count (15). Should run the browser research workflow: search Google Maps for category + Austin, build candidate list from visible results, cross-check via business name + city web search to verify website status. Should apply the 4-tier website status classification (No site found / Social only / Weak site / Has site) — prioritize No site + Social only as Hot. Should score: Hot (no site + active + phone + within radius), Warm (weak site), Cold (has site), Skip (closed/duplicate/out of scope). Should output Local SMB chat table (Score | Business | Category | Area | Distance | Website status | Website/Social | Phone | Why prospect | Confidence). Should add 'Best first outreach targets' top 3 with reasoning. Should reference references/local-prospecting.md. Should warn against bulk-scraping Google Maps (ToS violation) — browser-assisted research only.",
      "assertions": [
        "Identifies Local SMB branch",
        "Asks about business category if not specified",
        "Defaults radius to 20km",
        "Runs browser research workflow",
        "Applies 4-tier website status classification",
        "Uses Hot/Warm/Cold/Skip scoring",
        "Outputs Local SMB chat table columns",
        "Adds top 3 outreach targets",
        "References local-prospecting.md",
        "Warns against bulk-scraping Google Maps"
      ],
      "files": []
    },
    {
      "id": 6,
      "prompt": "I have a list of 200 prospect emails from Apollo. How do I know which ones are deliverable before I start outreach?",
      "expected_output": "Should explain the deliverability validation step in Phase 3. Should recommend Truelist (the integration in this pack) for bulk validation. Should explain the email_state classification output: ok (deliverable), email_invalid (bounces, exclude), risky (deliverable with risk like role or disposable, include cautiously), unknown (couldn't determine, skip or re-verify), accept_all (catch-all domain, include cautiously). Should warn that Apollo data accuracy is typically 60-80% — sending without validation will tank sender reputation (bounce rate >2% triggers ISP throttling and reputation damage). Should recommend the workflow: bulk POST to /api/v1/verify or CSV upload → keep ok, include risky/accept_all cautiously, exclude email_invalid, re-verify unknown → hand off to outreach. Should note Truelist also has an official MCP server for agent-driven validation. Should note cold email reputation is hard to recover once damaged — validation is non-negotiable, not optional. Should mention Hunter and Snov as alternatives with built-in verification. Should reference truelist.md integration guide.",
      "assertions": [
        "Recommends Truelist for bulk validation",
        "Explains email_state values (ok, email_invalid, risky, unknown, accept_all)",
        "Warns Apollo accuracy is 60-80%",
        "Cites 2% bounce rate threshold for reputation damage",
        "Recommends workflow: validate, keep ok, exclude email_invalid",
        "Mentions Truelist MCP server for agent workflows",
        "Mentions cold email reputation is hard to recover",
        "References truelist.md or data-sources.md"
      ],
      "files": []
    },
    {
      "id": 7,
      "prompt": "I just built a tool that automates failed-payment follow-up for gym owners. I have no customers yet. Help me find my first ten — the people who are actually dealing with this problem right now.",
      "expected_output": "Should select the Demand-signal branch (early-stage, first customers, evidence-of-demand) and load references/demand-signals.md — NOT the SMB/B2B list-building branches. Should start with a product brief, then mine the five signal buckets (explicit demand / pain / workaround / switching / timing) across public discourse (forums, communities, reviews, GitHub issues, job posts) — using last30days for recency, social-fetch/scraping to read original pages, not qualifying from snippets. Should score prospects on demand-fit (pain 25 / product fit 25 / timing 20 / reachability 15 / evidence quality 15, 0-100 with bands) rather than ICP-fit Hot/Warm/Cold, and require a cited public signal for every primary-shortlist prospect. Should draft source-based openers but never auto-send. Should produce an evidence report (verdict → ICP → top prospect → shortlist with sources+scores → repeated patterns → 7-day manual outreach plan → limits) and label prospects as 'potential customers based on public signals,' not confirmed buyers. Should honor the compliance guardrails including no data brokers/leaked data and no sensitive-trait targeting.",
      "assertions": [
        "Selects the Demand-signal branch, not the SMB/B2B/SaaS list-building branches",
        "Mines the five signal buckets from public discourse rather than contact databases",
        "Uses recency/original-source tooling (last30days, social-fetch, scraping) and does not qualify from snippets",
        "Scores on the demand-fit rubric (0-100 weighted), not ICP-fit Hot/Warm/Cold",
        "Requires a cited public signal for every primary-shortlist prospect",
        "Drafts openers but never auto-sends; labels prospects as potential-based-on-public-signals",
        "Produces the evidence report structure with a 7-day manual outreach plan and limits"
      ],
      "files": []
    }
  ]
}

---

Supporting file: references/b2b-prospecting.md

B2B Prospecting Reference

For when the user sells to non-SaaS B2B — services, agencies, manufacturers, mid-market and enterprise companies, professional services firms.

---

ICP Signals That Matter (B2B branch)

Firmographic signals

• Industry / vertical — NAICS or SIC codes if precision matters
• Company size — headcount band, revenue band, location count
• Geography — relevant for time zones, regulations, on-site requirements
• Business model — service vs product vs distribution; B2B vs B2B2C
• Ownership — independent, PE-backed, public, family-owned — affects buying motion

Buying signals

• Trigger events: new C-level hire, recent acquisition or divestiture, IPO/funding, opening a new location, recent rebrand, expansion announcement
• Vendor signals: posting RFPs publicly, switching costs in last quarterly report, contract renewal windows
• Operational signals: recent layoffs (cost pressure) or rapid hiring (capacity pressure)
• News mentions: launching new initiative, entering new market, regulatory change forcing action
• PR / press: anything that signals "this company is changing right now"

Decay signals

• Multiple bankruptcies or PE-stripped operations
• Negative growth + cost-cutting headlines
• Ownership stagnation (small family-owned, no growth incentive)
• Buyer turnover (3+ Marketing Directors in 2 years)

---

Discovery Sources (B2B branch)

Tier 1 — primary discovery

• Apollo: best general B2B firmographic + contact discovery
• ZoomInfo: enterprise B2B + intent signals (mid-market+)
• LinkedIn Sales Navigator: industry + role + signal search; the gold standard for decision-maker mapping (manual)
• Clay: when you need custom waterfall lookups (e.g., enrich Apollo records with Hunter + Clearbit)

Tier 2 — industry-specific directories

• Crunchbase / Pitchbook: funded businesses
• D&B Hoovers: large traditional B2B firmographics
• State / national business registries: for verified incorporation data
• Industry association membership rosters: trade groups often publish member lists
• Trade show exhibitor lists: signals active participation in a vertical
• Procurement databases (Procore for construction, e.g.): vertical-specific signals

Tier 3 — trigger event monitoring

• Google Alerts / Feedly: trigger keywords ("acquired," "hires," "expansion," "raises," "announces")
• PR Newswire / Business Wire: company-controlled announcements
• SEC filings (public companies): material change disclosures
• State filings: new entity formation, dissolution

---

Qualification Checklist (B2B branch)

• Industry / vertical matches ICP (use a recognized classification if possible)
• Company size within range (employees or revenue)
• Geography fits
• At least one trigger event in last 90–180 days
• Decision-maker role exists (CEO, COO, VP Operations, Director of X — match buyer profile)
• Email contact verifiable (named role > info@ catchall)
• Source URLs captured for firmographic claims
• No disqualifiers (closed, acquired-paused, multi-bankrupt, off-ICP)

---

Output Columns (B2B branch)

Recommended CSV columns:

score,company,domain,industry,naics_code,size_band,revenue_band,country,city,trigger_event,trigger_date,contact_name,contact_title,contact_email,email_status,linkedin_url,source_urls,why_prospect,confidence,verified_date,notes

For chat table, condense to: Score | Company | Industry | Size | Trigger | Contact | Email status | Confidence.

---

Top Outreach Targets Selection (B2B)

Prioritize for the top 3–5 hot leads:

1. Trigger event recency — 30 days beats 6 months
2. Trigger event specificity — new CMO hire in your buyer's role beats "company in the news"
3. Decision-maker access — named contact with verified email + LinkedIn beats role-only
4. Vertical fit precision — exact NAICS match beats "adjacent industry"

Each top target rationale names the trigger and decision-maker: "Hired new VP of Marketing 14 days ago; verified email; mid-market manufacturer matching ICP."

---

Common Mistakes (B2B)

1. Treating B2B like SaaS — funding rounds matter less; PE ownership and acquisition activity matter more.
2. Trying to verify private company revenue precisely — most public databases approximate. Use size bands, not point estimates.
3. Ignoring procurement complexity at enterprise scale — your prospect contact list may not include the actual approver.
4. Cold-emailing executive assistants — they're not the buyer and they will flag your outreach as spam.
5. Source URL hygiene — without source lineage, you can't defend a contact under GDPR DSAR or CAN-SPAM challenge.
6. Stopping at one source — Apollo can be 60% accurate on small businesses. Cross-verify with LinkedIn or the business website.

---

Supporting file: references/compliance.md

Prospecting Compliance Reference

The legal and platform-ToS constraints that apply to prospect list building. Read first, every engagement.

Operational guidance, not legal advice. For high-volume programs or programs touching EU/UK residents, run your setup past a privacy attorney.

---

United States — CAN-SPAM (downstream)

CAN-SPAM regulates the cold email send, not the list build. But the list build matters because:

• You must be able to identify the source of every email address you contact (required if challenged)
• The "from" line and email content rules apply at send time — but you can't lie about how you got the contact
• Opt-out requests must be honored within 10 business days and tracked

For prospecting specifically: capture and retain the source URL + date for every contact you add to a list. CAN-SPAM doesn't require it explicitly, but defending your sender practices does.

---

EU / UK — GDPR

The strictest applicable framework. Triggers when:

• Your prospect resides in EU/UK
• You're processing personal data (any identifiable info, including business emails tied to a named person)

Lawful bases for cold B2B outreach

You have three credible options:

1. Legitimate interest (most common for B2B). Requires:

   • The contact is in a business role likely to be interested in your offer
   • The data was collected from a public, business-context source
   • You provide a clear opt-out
   • You can articulate the legitimate interest test in writing

2. Consent — typically not feasible for cold outreach (you don't have consent before first contact)

3. Existing customer relationship — only applies to current customers, not prospects

What you must do

• Capture source + date + lawful basis for every contact
• Honor data subject access requests (DSARs) — you must be able to disclose, correct, or delete on request
• Include a privacy notice / opt-out in the first outreach
• Don't store personal data longer than necessary for the legitimate interest

What disqualifies a list

• Bulk-scraped LinkedIn data — explicit ToS violation + GDPR risk
• Email addresses purchased from a list broker without source provenance
• "Anyone @ this domain" guessed emails sent without verification (multiplies risk + bounces)

---

Canada — CASL

Stricter than CAN-SPAM. Cold B2B outreach requires:

• Express consent (explicit opt-in) — typically not present for cold prospecting
• OR implied consent — existing business relationship within 24 months, OR business address publicly published on the company's own site for the purpose of receiving such communications

Practical implication for Canadian prospects: relying on the publicly-published-address exception is the most defensible cold prospecting basis in Canada. You must include sender identification, mailing address, and an unsubscribe mechanism in every message.

---

Platform Terms of Service

LinkedIn

• Sales Navigator as a research tool: fine
• Scraping LinkedIn at any scale: explicit ToS violation. Banned accounts are permanent. Don't.
• Apollo, Clay, and ZoomInfo claim LinkedIn-overlap data through various legitimate channels — verify their data sources before assuming compliance
• InMail and Connection Requests: governed by LinkedIn's own messaging rules, not by CAN-SPAM/GDPR (because LinkedIn-internal)

Google Maps

• ToS prohibits bulk extraction or productizing Maps data
• Browser-assisted research as a discovery aid: acceptable
• Storing Place IDs or large structured Maps data in your CRM: explicit ToS prohibition
• Use Maps to find local businesses, then cross-source from the business's own site for the data you retain

Apollo / ZoomInfo / Clearbit

• All have their own ToS limiting reselling, downstream sharing, and use cases
• Read your contract — typically you can use the data for your own outreach but not productize it
• Don't share extracts publicly (e.g., on a leaderboard, in a public report)

Crunchbase

• Free tier is read-only for personal use
• Paid tier permits broader use within contractual scope
• API access requires paid Pro+ tier

---

Anti-Patterns (Don't Do These)

1. Bulk-scraping LinkedIn / Google Maps / Yelp. Browser-assisted research is OK; automated scrapers pointed at these platforms are not. Firecrawl and Browserbase are fine for an individual prospect's own website (the URL you found through manual discovery) — not for the platforms hosting prospects.
2. Buying lists from random vendors without source provenance. You inherit their legal exposure.
3. Guessing emails and sending unverified. Bounce rates over 2% destroy sender reputation; legally, you can't claim a "legitimate interest" basis for an email you fabricated.
4. Harvesting personal email addresses (Gmail, personal Outlook, etc.) from public profiles. Personal addresses raise GDPR risk significantly.
5. Storing data you don't need. Minimize retention. Don't keep prospect lists forever — GDPR right to deletion applies.
6. Skipping the lawful basis documentation. If challenged, you need to show your work. Capture source URL + collection date for every contact.
7. Reselling prospect lists. You may not have the right to share them downstream. Read your data provider contracts.
8. CAPTCHA bypass / login wall bypass. Even if technically possible, this signals bot behavior and violates virtually every ToS.

---

Quick Audit Checklist

Before shipping a list to the user (or downstream to cold-email):

• Every contact has a source URL + collection date
• No contacts sourced from scraped LinkedIn data
• No Google Maps Place IDs or large Maps-structured data retained
• Lawful basis documented (legitimate interest test for B2B, or relevant alternative)
• Email addresses validated (deliverability check before outreach)
• Personal addresses (Gmail, etc.) flagged or excluded
• Source provider contracts permit the intended use case
• Retention plan documented (when to delete)
• First outreach will include unsubscribe + privacy notice (downstream concern for cold-email skill, but mention it now)

---

Supporting file: references/data-sources.md

Prospecting Data Sources

Tool selection guide for prospecting across all three branches.

---

Tool selection by goal

---

Apollo

Use for: General B2B / SaaS firmographic + contact data. Best starting point if you don't already have a list.

Strengths:

• Large database (>200M contacts, >60M companies)
• Strong filtering UI (industry, size, technologies, signals)
• Integrated email + LinkedIn finder
• Pay-as-you-go and tiered plans

Watch out for:

• Data freshness varies — re-verify before scoring as "Hot"
• Email accuracy ~60–80% — always validate
• Bulk export limits apply

Integration: see apollo.md (../../../tools/integrations/apollo.md)

---

Clay

Use for: Multi-source enrichment, waterfall lookups, custom scoring logic. When list quality matters more than list size.

Strengths:

• Waterfall logic: try Apollo first → fallback to ZoomInfo → fallback to Clearbit
• 100+ data provider integrations
• AI-powered enrichment (LLM-driven extraction from URLs)
• Custom columns + scoring formulas
• Native MCP server

Watch out for:

• Per-credit pricing can spike on large lists
• Complexity overhead — easy to over-engineer workflows

Integration: see clay.md (../../../tools/integrations/clay.md)

---

ZoomInfo

Use for: Enterprise B2B + intent data. Mid-market+ buyer profiles.

Strengths:

• Enterprise-grade firmographic depth
• Intent signals (companies searching topics relevant to your offer)
• Best-in-class for >$50K ACV B2B sales
• Native MCP server

Watch out for:

• Expensive ($15K+/yr starter)
• Overkill for SMB prospecting
• Locked into multi-year contracts typically

Integration: see zoominfo.md (../../../tools/integrations/zoominfo.md)

---

Clearbit

Use for: Email → company enrichment, anonymous visitor identification (Clearbit Reveal).

Strengths:

• Strong company enrichment (industry, size, funding, tech stack)
• Email lookup by domain
• Reveal: identify anonymous site visitors at company level
• API-first

Watch out for:

• HubSpot acquisition (2023) — bundled into HubSpot Breeze Intelligence now
• Standalone API still available but pricing/access depends on tier

Integration: see clearbit.md (../../../tools/integrations/clearbit.md)

---

Hunter / Snov

Use for: Email pattern discovery + lightweight verification on small lists.

Hunter strengths:

• Domain-based email discovery
• Built-in deliverability verification
• Free tier reasonable for occasional use

Snov strengths:

• Email finder + drip campaigns (overlap with outreach tooling)
• Bulk verification
• Cheaper than Hunter at scale

Watch out for:

• Both are pattern-guessing tools — accuracy depends on the target company's email pattern being inferable
• Always run results through a dedicated validator (Truelist or similar) before outreach

Integrations: see hunter.md (../../../tools/integrations/hunter.md), snov.md (../../../tools/integrations/snov.md)

---

Truelist

Use for: Email deliverability validation before adding contacts to outreach lists. Critical safety step.

Strengths:

• Single-email sync verification (/api/v1/verify_inline) + bulk async (/api/v1/verify)
• Returns email_state (ok / email_invalid / risky / unknown / accept_all) + email_sub_state (email_ok / is_disposable / is_role / unknown_error / failed_smtp_check) + did-you-mean typo suggestions
• Catches catch-all domains, role accounts, spam traps, disposable providers
• Official MCP server for agent-driven workflows (Claude, Cursor, VS Code)
• Official SDKs in 7 languages + framework integrations (Django, Laravel, Next.js, Rails, React, Svelte, Vue, WordPress)
• Native integrations with Mailchimp, Klaviyo, HubSpot, Zapier, Make, n8n, Clay, Salesforce, more
• Pay-per-email pricing

Why this matters: Cold email reputation craters when bounce rates exceed 2%. Validating before sending is non-negotiable. Apollo/ZoomInfo/Hunter data is often 60–80% accurate — Truelist catches the rest.

Integration: see truelist.md (../../../tools/integrations/truelist.md)

---

LinkedIn Sales Navigator

Use for: Manual decision-maker discovery. The gold standard for B2B / SaaS prospecting but only when used as a research tool.

Strengths:

• Most accurate decision-maker data in the industry
• Real-time job changes, posts, signals
• Lead lists, alerts, saved searches
• Inmail credits (separate channel from cold email)

Hard rules:

• Never bulk scrape. LinkedIn aggressively bans scrapers. Account ban risk is real and permanent.
• Use Sales Nav as a research interface — open profiles, read, take notes, capture key data manually.
• Apollo and other tools claim LinkedIn data via partnerships / public mirroring — verify the source legitimacy before assuming compliance.

Integration: no MCP or API access at consumer level. Manual research only.

---

BuiltWith / Wappalyzer

Use for: Tech stack qualification (SaaS branch).

BuiltWith:

• ~50K+ technologies tracked
• API + bulk lookups (paid)
• Historical data (when stack changed)

Wappalyzer:

• Free browser extension; paid API
• Lighter coverage than BuiltWith
• Faster for one-off lookups

Cross-reference both for high-confidence tech stack signals.

---

Crunchbase

Use for: Funding signals (SaaS branch).

Strengths:

• Free tier shows recent funding events
• Paid (Pro / Enterprise) unlocks alerts and deep history
• API access for paid users

Watch out for:

• Coverage is best for VC-backed companies; bootstrapped + small businesses underrepresented
• Self-reported data — verify funding amounts independently

---

GitHub (stargazers / forks / watchers)

Use for: Developer-intent prospecting. Especially powerful for dev-tool SaaS — stargazers of competitor or category-defining repos are in-market signal.

Strengths:

• Public API, no scraping concerns
• High signal quality (a starred repo = explicit interest)
• Forks are an even stronger signal (intent to modify, not just bookmark)
• Bundled github-prospects.js CLI handles pagination + enrichment + CSV output
• Free with 5,000 req/hr authenticated rate limit

Watch out for:

• Only ~5–20% of users publish email — pair with Apollo/Clay/Hunter for enrichment
• Very-popular repos (100K+ stars) are mostly noise; smaller targeted repos (5K–25K) give better signal density
• Most prospects are individuals, not company contacts directly — need to figure out their company from company field or LinkedIn

Integration: see github.md (../../../tools/integrations/github.md)

---

Firecrawl / Browserbase (single-target site research)

Use for: Programmatically extracting content from a prospect's own website that you already found via discovery on platforms like Google Maps, Yelp, or LinkedIn. Not for scraping those platforms themselves.

Firecrawl

• Best for: "Just give me the page as markdown" — Local SMB website status checks, B2B company about/team page extraction, structured field extraction
• Strengths: Low overhead, returns clean LLM-ready markdown, handles most JS-rendered sites, has an MCP server
• API + MCP + SDKs: Node, Python, Go, Rust

Browserbase

• Best for: When you need real Chromium — JS-heavy pages, cookie consent dialogs, form submission to reach a contact page, session state
• Strengths: Full browser control via Playwright/Puppeteer; Stagehand provides AI-friendly natural-language extraction; session recordings for debugging
• API + MCP (Stagehand) + SDKs: Node, Python

Critical compliance line

Both tools can technically point at any URL. The hard rule:

• ✓ OK: extracting content from a single business's own website (joescoffeeshop.com) that you found through manual discovery
• ✗ NOT OK: pointing them at google.com/maps, LinkedIn search results, Yelp listings, or any platform whose ToS prohibits bulk extraction

Discovery happens on platforms (manual browser-assisted research). Extraction happens on individual public business sites.

Integrations: see firecrawl.md (../../../tools/integrations/firecrawl.md), browserbase.md (../../../tools/integrations/browserbase.md)

---

RB2B / Clearbit Reveal

Use for: Identifying anonymous site visitors as warm intent signals.

Strengths:

• Pixel-based visitor → company identification
• High-intent: they came to your site, they're already in research mode
• Slack / email alerts on key visits

Watch out for:

• Privacy/GDPR considerations — verify your privacy policy disclosures
• Person-level identification raises higher concerns than company-level

Integration: see rb2b.md (../../../tools/integrations/rb2b.md)

---

Free / browser-only fallbacks

When the user has no paid tools, lean on:

• Google Search — exact business name + city + role searches
• LinkedIn (manual, no scraping) — company pages, employee lookups
• Crunchbase free tier — funding events
• Wappalyzer browser extension — tech stack at a glance
• Hunter.io free tier — 25 lookups/month
• Google Maps — for Local SMB discovery
• Business websites + About pages — primary source for any claim
• News sites + press releases — trigger event monitoring via Google Alerts

Slower than tooled-up workflows, but produces high-quality smaller lists if the user is willing to do the work.

---

Sequencing recommendations

A typical full-stack prospecting workflow:

1. Define ICP from product-marketing context (no tools needed)
2. Initial list from Apollo or ZoomInfo (firmographic filter)
3. Enrich with Clay (waterfall: tech stack, funding, trigger events)
4. Decision-maker mapping in LinkedIn Sales Nav (manual)
5. Email pattern discovery with Hunter or Apollo's built-in
6. Email validation with Truelist before final list
7. Hand off to cold-email skill for outreach copy

Adapt this sequence based on which tools the user actually has.

---

Supporting file: references/demand-signals.md

Demand-Signal Discovery (Find Your First Customers)

The other three branches build a list from who fits (firmographics, technographics, proximity). This branch builds a list from who is already showing the pain — the early-stage motion where you have a product and a hunch but no customer base yet, and you need your first ten real conversations. You are not filtering a database; you are mining recent public discourse for people describing the exact problem you solve, then linking every prospect to the evidence.

Use this branch when the user is pre-product-market-fit, launching something new, or looking for design partners, beta users, or first customers rather than a scaled outbound list. It reuses the shared five phases and every compliance guardrail in SKILL.md; what changes is where you look, how you score, and what you ship.

Pattern credit: the framework here is re-expressed from the open-source first-customer-finder Codex skill (Kappaemme, MIT), extended with our live-recency tooling.

What makes this branch different

A prospect here without a cited pain, need, or timing signal is a speculative fit — it does not belong in the primary shortlist. Evidence is the entry ticket.

Step 1 — Product brief (before any searching)

Define, specifically enough to reject weak matches:

• product and the promised outcome
• primary user and the economic buyer (often different)
• the urgent job to be done
• the current alternative or workaround being replaced
• the likely adoption trigger (what makes now the moment)
• geography / language constraint
• clear disqualifiers

Don't start broad collection until the brief is sharp. Pull from .agents/product-marketing.md if it exists.

Step 2 — Mine the five signal buckets

Search several angles, not one query repeated. Adapt wording to how the audience actually talks (mine their vocabulary from organic content first — see the ad-creative hook-system's organic-language note for the same idea).

1. Explicit demand — "looking for," "recommend a tool for," "alternative to [X]," "does anything exist that," "how do you all handle."
2. Pain — "takes hours," "so manual," "hate that," "keeps breaking," "biggest frustration with," "why is there no."
3. Workaround — spreadsheets, copy-paste, a VA, a Zapier chain, a script, a template, any repeated manual step that your product would replace.
4. Switching — cancellation, migration, "moving off [competitor]," a missing feature, a pricing complaint, competitor frustration.
5. Timing — a public launch, a new hire for the relevant function, expansion, a new workflow or regulation, an integration announcement — a current event that makes the product relevant now.

Use our live-recency edge. A generic skill relies on whatever a web search surfaces; you have better:

• last30days — Reddit, Hacker News, X, YouTube, and web signals from the last 30 days. This is the single highest-value tool for this branch: recency is the timing signal.
• social-fetch — pull the full content of a specific post/thread you find, normalized.
• scraping / Firecrawl / Browserbase — read the original public page (a forum thread, a GitHub issue, a review), never qualify from a search snippet alone.
• deep-research — for a multi-source sweep with adversarial verification when the wedge is broad.
• competitor-profiling / customer-research — competitor switching signals and review-mining for the pain language.

Step 3 — Source mix (public only)

Forums and public community threads · public social posts and replies · product and app-marketplace reviews · GitHub issues and feature requests · public company pages, job posts, changelogs, launch announcements · "looking for a tool" posts and directories.

Avoid private groups, gated communities, data brokers, leaked datasets, and any source whose terms prohibit access — the same compliance guardrails as every other branch (see SKILL.md), including the no-sensitive-traits rule.

Business/professional context only. Qualify and reach out only where someone is posting in a professional or business capacity about a work problem (a founder in an indie-hackers thread, a developer in a GitHub issue, an ops lead in a subreddit for their role). Exclude personal-distress contexts entirely — health, financial hardship, addiction, grief, or any consumer support forum where people are venting personal problems, even if your product is tangentially relevant. When the motion is genuinely consumer (B2C), a public pain post is not on its own a lawful basis for cold outreach — reach people through the channel's own norms (reply publicly where replying is expected) and never DM a stranger off a personal post.

Quote minimally, paraphrase by default, and link every material pain or timing signal.

Step 4 — Score on demand-fit (not ICP-fit)

The list-building branches score Hot/Warm/Cold on ICP fit. This branch scores 0–100 on demand fit — how strongly the evidence says this specific prospect wants this specific thing now. Score each dimension 0–5:

score = pain/5*25 + fit/5*25 + timing/5*20 + reachability/5*15 + evidence/5*15

An old explicit request can still count — but lower the timing score and label the date. A company that merely matches the industry with no evidenced trigger is not a qualified prospect here.

Prospect stages

• High intent — publicly requesting a solution or actively switching
• Problem aware — clearly describing the pain or an expensive workaround
• Trigger present — a current business event makes the product relevant
• Potential fit — ICP match, incomplete evidence → keep outside the primary shortlist

Evidence ledger (per qualified prospect)

Displayed name (company/project/public professional) · source title + URL · visible publication date or "date unavailable" · source type · the concise pain/timing signal · observed evidence vs. inference (label which) · score breakdown · freshness warning when the signal is stale.

Step 5 — Draft outreach, never send it

Recommend the most natural channel already associated with the source, and only where a reply is a normal part of that channel (reply in the public thread, respond via a public professional profile). Don't turn a public post into a private DM the poster didn't invite, and never contact someone off a personal-distress post. Draft one opener, under ~90 words, in this shape:

1. mention the public context naturally
2. connect it to the exact problem
3. explain the product in one sentence
4. ask one low-friction question

Never claim familiarity you don't have, never fabricate personal details, and never auto-send: no messages, connects, follows, comments, form submissions, or CRM records unless the user separately authorizes that action. This is the manual/gated posture from the marketing-loops guardrails.

Step 6 — Ship the evidence report

Lead with the most actionable evidence, in this order:

1. Verdict — does the product have reachable early-customer signal, or not yet? (An honest "not yet, here's why" is a valid answer.)
2. ICP — buyer, job, trigger, disqualifiers.
3. Top prospect — the single strongest evidence-backed candidate and why now.
4. Prospect shortlist — per prospect: source, pain signal, demand-fit score, stage, why-now, channel, opener.
5. Repeated patterns — pains and triggers recurring across prospects (these are your positioning and messaging gold).
6. Seven-day manual outreach plan — a low-volume validation sequence (e.g., contact the top 3 with one source-based question; share a mockup only after they confirm the pain; target three conversations and one design-partner commitment).
7. Limits — what evidence is missing and what must be confirmed through real conversations.

For a shareable standalone HTML version of this report, the JSON→HTML generator pattern in ad-creative's creative-review-page.md (../../ad-creative/references/creative-review-page.md) is the model (escape every value; keep it self-contained).

The honesty rules (non-negotiable)

• Every primary prospect links to at least one real public signal. No signal, no shortlist.
• Label the output "potential customer based on public signals" — never "interested," "will buy," or "has consented."
• Prefer ten strong matches over a long generic list. Make uncertainty and stale evidence visible.
• Personalize from the cited source, not from invented assumptions.
• Treat the shortlist as a research hypothesis to validate through conversations, not a customer database.

---

Supporting file: references/local-prospecting.md

Local SMB Prospecting Reference

For when the user sells to local small businesses — shops, gyms, restaurants, salons, clinics, professional services, contractors, real estate, fitness studios, dental practices.

Adapted from and generalized beyond the local-client-prospector pattern (browser-assisted discovery + website status classification + proximity scoring).

---

ICP Signals That Matter (Local SMB branch)

Operational signals

• Active business — Google Business Profile updated, recent reviews, recent hours updates
• Recent activity — open right now, regular hours posted, recent photos uploaded by owner
• Customer engagement — owner responding to reviews, posts on social, active calendar (for service businesses)

Online presence signals (the core SMB qualification axis)

The reference local-client-prospector skill uses website status as the primary qualification — port this directly. Four classifications:

Proximity signals

• Distance from the user's location or service area
• Density — clusters of similar businesses in one area = neighborhood targeting opportunity
• Travel time — useful when in-person discovery, install, or service delivery is required

Decay signals

• Closed permanently (Google Maps banner)
• Reviews paused or business listing reported as closed
• Last activity (review, post) >12 months ago

---

Discovery Sources (Local SMB branch)

Primary

• Google Maps (browser, manual) — search "category near [location]" and walk the visible results. Cross-check details. Don't bulk-extract.
• Yelp — secondary verification; complementary categories
• Bing Local / Apple Maps — different coverage on smaller businesses
• Facebook Pages search — many SMBs are Facebook-only

Cross-verification

• Business's own website (if any)
• Industry directories (e.g., Healthgrades for medical, OpenTable for restaurants, Avvo for legal)
• Local Chamber of Commerce listings
• State business registries for incorporation status
• Search results for "[business name] [city]" to discover non-Maps presence

---

Browser Research Workflow

1. Open a browser and search Google Maps for the category near base_location
2. Build a candidate list from visible local results, search results, and public directories
3. For each candidate, inspect public sources to fill required fields
4. Search the exact business name plus city/town to check whether a standalone website exists
5. Classify website status per the table above
6. Mark confidence: High (2+ sources), Medium (1 source + consistent evidence), Low (incomplete/ambiguous)

When the user explicitly asks for subagents AND subagents are available, split candidates into non-overlapping batches and ask each subagent to verify only website/social/contact status. Don't use subagents for the primary search if it slows progress.

Optional: programmatic verification with Firecrawl or Browserbase

Once you have a candidate's website URL (found via manual Maps/Yelp discovery), you can speed up website-status classification by hitting the URL programmatically:

• Firecrawl for simple "is this site live, modern, mobile-friendly, conversion-flow-equipped" reads — returns clean markdown you can inspect
• Browserbase when the candidate site requires JS rendering, has a cookie consent dialog, or you need session state

Strict line: use these on the individual business's URL. Don't point them at Google Maps, Yelp, or any platform whose ToS prohibits bulk extraction — discovery stays manual.

See data-sources.md for setup details.

---

Qualification Checklist (Local SMB branch)

• Business is active (recent reviews or activity in last 6 months)
• Category matches user's service offering
• Distance / proximity within target radius
• Website status classified
• Phone or contact channel verified
• At least one cross-source confirms business operates at the listed address
• Not a duplicate / chain location / out-of-scope category
• Not closed permanently

---

Lead Scoring (Local SMB)

Use this simple rubric (matches local-client-prospector pattern):

---

Output Columns (Local SMB branch)

Chat table (≤15 rows):

| Score | Business | Category | Area | Distance | Website status | Website/Social | Phone | Why it's a prospect | Confidence |

CSV:

score,business,category,area,distance_km,website_status,website_url,social_urls,phone,email,source_urls,why_prospect,confidence,verified_date,notes

Rules:

• Keep "Why it's a prospect" short and actionable
• Use Not found instead of leaving blank fields
• Include source links sparingly, not all of them
• After the table, add Best first outreach targets with the top 3 leads and one practical reason each
• If confidence is low, state exactly what remains uncertain

---

Top Outreach Targets Selection (Local SMB)

Prioritize for the top 3 hot leads:

1. No site / social only + phone present = clearest service opportunity
2. High review count = active, established business with real customers
3. Owner-responded reviews = engaged owner = more likely to evaluate a vendor
4. Industry alignment with your service specialty beats generic category match

Each top target rationale should be one sentence naming the gap and the signal: "No standalone website (cross-checked); 80+ Google reviews with owner replies; 2 km from target area."

---

Compliance Notes (Local SMB-specific)

The local branch is the most scraping-sensitive of the three motions. Specifically:

• Google Maps Terms of Service prohibit bulk extraction. Treat browser visits as research, not as data acquisition.
• Don't store full Google Maps Place IDs in your CRM — the ToS limits storage of Maps data.
• Public business contact channels only: published phone, contact form, info@ email. Don't reach individual employees through their personal channels.
• Owner/operator name when published on the business's own site is OK to use. If you only got it from LinkedIn, mark the source.

---

Common Mistakes (Local SMB)

1. Bulk-scraping Google Maps — fastest way to violate ToS and lose the research channel.
2. Treating Google Maps data as truth — listings go stale. Cross-check hours, status, and reviews.
3. Skipping the website status cross-check — finding "no site" on Maps doesn't mean no site exists; do an exact-name web search before classifying.
4. Targeting only the largest businesses — they're already covered by other providers. The 2–5 employee SMBs are the under-served opportunity.
5. Generic outreach to all hot leads — local SMBs respond better to outreach that names their specific gap ("I noticed your menu isn't visible on mobile") than generic pitches.
6. Ignoring chains and franchises as Skip — sometimes the franchisee is the buyer and they have local marketing authority. Verify before skipping.

---

Supporting file: references/saas-prospecting.md

SaaS Prospecting Reference

For when the user sells SaaS or digital services to other SaaS companies / digital businesses.

---

ICP Signals That Matter (SaaS branch)

Beyond standard firmographics (industry, size, geography), SaaS prospects are qualified by:

Technographic signals

• Tech stack — do they use complementary tools (your integration target) or competing tools (a switch opportunity)?
• Recent stack changes — adding/removing tools signals active vendor evaluation
• Custom-built vs off-the-shelf — DIY tooling often means a buyer who'd benefit from your product
• Free/freemium plan signals — using a free competitor means they may be ready to upgrade

Growth signals

• Funding round — Series A / B / C in last 6 months = budget + new hires + tool needs
• Headcount growth — 10%+ growth in last quarter signals scaling pressure
• Hiring signals — specific role openings (e.g., "Head of RevOps" → ICP for revops tooling)
• Product velocity — frequent shipping, new features, blog posts = healthy growth motion
• Open positions for your buyer's role — if you sell to Marketing Ops and they're hiring one, that's a signal

Decay signals (downgrade scoring)

• Layoffs in target department
• Funding round >2 years ago with no follow-up
• Product hasn't shipped in 6+ months
• Team page shows founders only (very early — may not have budget)

---

Discovery Sources (SaaS branch)

Combine 2+ sources for cross-verification.

Tier 1 — primary discovery

• Apollo: firmographic + technographic + contact data. Good for building large initial lists.
• Clay: waterfall enrichment, custom scoring, multi-source merges. Best for high-quality smaller lists.
• ZoomInfo: enterprise-grade firmographic + intent signals. Expensive; mid-market+.
• LinkedIn Sales Navigator: decision-maker mapping. Use manually, never bulk scrape.

Tier 2 — technographic / growth signals

• BuiltWith: tech stack lookups, find sites using specific tools
• Wappalyzer: free browser extension + API; lighter tech stack signal
• Crunchbase: funding rounds, headcount, founders
• Pitchbook: deeper investor data (enterprise/paid)
• ProductHunt: recent launches, builder audience
• Hacker News / Show HN: technical builders launching products

Tier 3 — buying signals

• Job boards (LinkedIn Jobs, Indeed, AngelList): role openings as signals
• RB2B / Clearbit Reveal: visitor identification (warm anonymous traffic)
• GitHub stars/forks of competitor or adjacent repos: developer-level intent signal (see tools/integrations/github.md and the github-prospects.js CLI). Especially strong for dev-tool SaaS — a developer who starred vercel/next.js last week is in-market for adjacent Next.js infrastructure.
• Recent blog posts / changelog: product direction signals
• G2 reviews mentioning competitor switches: explicit dissatisfaction signal

GitHub prospecting pattern (when audience is developers)

For dev-tool SaaS, GitHub is one of the highest-quality discovery channels:

1. Identify 3–5 "anchor" repos: your direct competitors, your category leader, complementary tools your buyer uses
2. Pull stargazers (or forks for stronger intent) via node tools/clis/github-prospects.js stargazers <owner/repo> --enrich --with-company --format csv
3. Filter to users with company set — these are the easiest to enrich downstream
4. Pair with Apollo/Clay/Hunter to lookup email by name + company
5. Validate with Truelist before adding to outreach list

Tradeoffs: GitHub yields email for only ~5–20% of users directly. The strength is the signal quality — a stargazer of a niche dev tool is genuinely in-market in a way Apollo firmographics alone can't tell you.

---

Qualification Checklist (SaaS branch)

For each candidate, verify:

• Industry vertical matches ICP
• Company size (headcount) within range
• Tech stack includes (or notably excludes) a target technology
• Funding stage matches buyer maturity
• At least one growth signal in last 90 days (funding, hiring, product velocity)
• Decision-maker role exists at the company (named or inferable from job listings)
• Email contact verifiable
• No disqualifiers (closed, acquired-and-paused, layoffs, ICP miss)

---

Output Columns (SaaS branch)

Recommended CSV columns:

score,company,domain,industry,size_band,country,funding_stage,last_round_date,tech_stack_match,signal,signal_date,contact_name,contact_title,contact_email,email_status,linkedin_url,source_urls,why_prospect,confidence,verified_date,notes

For chat table, condense to: Score | Company | Industry | Size | Signal | Contact | Email status | Confidence.

---

Top Outreach Targets Selection (SaaS)

Prioritize for the top 3–5 hot leads:

1. Strongest signal recency — funding 30 days ago beats funding 9 months ago
2. Tech stack match strength — known integration partner beats inferred fit
3. Decision-maker named with verified email — beats role-pattern-guessed email
4. Multi-source confidence — both Apollo + Crunchbase agree beats one source

Each top target gets a one-sentence outreach rationale that names the specific signal: "Raised Series B 30 days ago; hiring Head of RevOps; verified VP of Ops email."

---

Common Mistakes (SaaS)

1. Buying lists from Apollo wholesale without re-verifying email and re-checking firmographics. Stale data is the norm.
2. Treating tech stack data as 100% accurate. BuiltWith and Wappalyzer miss things; Clay's waterfalls miss things. Cross-check.
3. Targeting Series C+ for early-stage SaaS sellers. The buyer profile is wrong — too many procurement hoops, too much red tape.
4. Targeting Series Pre-Seed seed for products requiring meaningful budget. They have neither budget nor evaluator bandwidth.
5. Ignoring intent data when it exists (ZoomInfo Intent, 6sense, etc.) — pre-warm signals beat cold every time.

---

Supporting file: tools/REGISTRY.md

Marketing Tools Registry

Quick reference for AI agents to discover tool capabilities and integration methods.

How to Use This Registry

1. Find tools by category - Browse sections below for tools in each domain
2. Check integration methods - See what APIs, MCPs, CLIs, or SDKs are available
3. Read integration guides - Detailed setup and common operations in integrations/

---

Tool Index

---

By Category

Analytics

Track user behavior, measure conversions, and analyze marketing performance.

Agent recommendation: Start with GA4 if using Google ecosystem. Use Mixpanel or Amplitude for deeper product analytics. Plausible for privacy-focused sites.

SEO

Search engine optimization tools for keyword research, rank tracking, and site audits.

Agent recommendation: Google Search Console is essential (free). Add Semrush or Ahrefs for competitive research. DataForSEO for programmatic SERP data. Keywords Everywhere for quick keyword lookups. RankParse for agent workflows where per-call cost matters — backlinks, domain authority, and tech stack at a fraction of enterprise pricing.

CRM

Customer relationship management and sales tools.

Agent recommendation: HubSpot for startups/SMBs. Close for high-velocity inside sales. Salesforce for enterprise.

Payments

Payment processing and subscription management.

Agent recommendation: Stripe is the default for SaaS. Paddle for built-in tax compliance.

Referral & Affiliate

Tools for referral programs, affiliate tracking, and partner management.

Agent recommendation: Rewardful or Tolt for Stripe-based SaaS. PartnerStack for enterprise partner programs. Dub.co for link attribution.

Email

Email marketing, transactional email, and automation platforms.

Agent recommendation: Resend for transactional (dev-friendly). Sequenzy for lifecycle email, sequences, and agent-driven email marketing. Postmark for deliverability. Customer.io for advanced automation. Kit for creators. Beehiiv for newsletters. Klaviyo for e-commerce email/SMS. ActiveCampaign for email + CRM combo.

SMS / Messaging

SMS and MMS marketing platforms and programmable messaging APIs.

Agent recommendation: Klaviyo SMS for ecom already on Klaviyo email. Postscript for Shopify-first depth. Attentive for mid-market+ wanting concierge support. Twilio (or Plivo for lower cost) for custom builds and transactional/auth. AudienceTap when AI creative or on-pack QR opt-in matters.

Advertising

Paid advertising platforms and campaign management.

Agent recommendation: Google Ads for search intent. Meta for demand generation. LinkedIn for B2B.

Automation

Workflow automation and integration platforms.

Agent recommendation: Zapier SDK for agents that need to interact with any app directly. Zaps for always-on automations.

CRO & A/B Testing

Conversion rate optimization, heatmaps, and experimentation.

Agent recommendation: Hotjar for understanding user behavior. Optimizely for running experiments.

Scheduling

Booking and appointment scheduling tools.

Agent recommendation: Calendly for general use. SavvyCal for personalized booking experiences.

Forms & Surveys

Form builders and survey platforms.

Agent recommendation: Typeform for engaging forms and surveys.

Messaging

In-app messaging, chat, and customer communication.

Agent recommendation: Intercom for in-app messaging and customer support.

Social Media

Social media scheduling, management, and analytics.

Agent recommendation: Buffer for scheduling and analytics across social platforms.

Video

Video hosting, creation, and AI generation.

Agent recommendation: HeyGen for AI avatar videos (MCP-enabled). Hyperframes for templated, data-driven video from code. Wistia for hosting and analytics.

Data Enrichment

Company and person data enrichment for sales and marketing.

Agent recommendation: Clearbit for enrichment. Apollo for prospecting and outbound. ZoomInfo for enterprise B2B data with intent signals. Clay for waterfall enrichment across multiple providers.

Email Verification

Pre-outreach email deliverability validation.

Agent recommendation: Truelist for any prospect list before outreach — Apollo/ZoomInfo/Hunter data accuracy is typically 60–80%, validation is non-negotiable to keep sender reputation healthy.

Developer Intent / GitHub

Discovery channel for dev-tool SaaS prospecting via GitHub stargazers, forkers, and watchers.

Agent recommendation: Use github-prospects.js CLI to pull stargazers/forks of 3–5 anchor repos (competitors, category leaders, complementary tools). Filter to users with company field set, then enrich missing emails via Apollo or Hunter, then validate via Truelist before outreach.

Site Scraping (single-target only)

Programmatic page extraction for individual public business sites — not for the platforms hosting prospects (Google Maps, LinkedIn, Yelp, Apollo, etc.).

Agent recommendation: Default to Firecrawl for static-ish pages and structured extraction. Use Browserbase when the site requires JS rendering, form interaction, cookie consent, or auth — and when you want session recordings for debugging. For both: discovery happens on platforms (manual browser); extraction happens on the prospect's own website URL. Don't point either tool at LinkedIn, Google Maps, Yelp, or similar.

Reviews

Review management and social proof platforms.

Agent recommendation: Trustpilot for consumer products. G2 for B2B software.

Push Notifications

Push notification delivery platforms.

Agent recommendation: OneSignal for web and mobile push notifications.

Webinar

Webinar and virtual event platforms.

Agent recommendation: Demio for marketing-focused webinars. Livestorm for full event engagement.

Sales Engagement

Sales engagement and outreach automation platforms.

Agent recommendation: Outreach for enterprise sales teams managing multi-touch sequences at scale.

Product Analytics

Product analytics, feature adoption tracking, and in-app guidance.

Agent recommendation: Pendo for tracking feature adoption and delivering targeted in-app guidance.

Competitive Intelligence

Traffic analytics, competitor benchmarking, and market research.

Agent recommendation: Similarweb for competitor traffic analysis and market benchmarking.

Audience Research

Audience intelligence and behavioral research tools.

Agent recommendation: SparkToro for discovering where your ICP spends time — what they read, watch, listen to, follow, and search for. Essential for customer research, content strategy, and media buying decisions.

Visitor Identification

Website visitor de-anonymization for B2B sales and marketing.

Agent recommendation: RB2B for identifying anonymous B2B website visitors and routing high-intent visitors to outreach tools. Pairs well with Clay for enrichment and Instantly/Lemlist for cold email.

Revenue Intelligence

Sales conversation analytics, call recording, and deal intelligence.

Agent recommendation: Gong for mining sales call transcripts for customer research, competitive intelligence, and coaching insights. Essential for revenue attribution and win/loss analysis.

AI Content

AI-powered content generation and optimization platforms.

Agent recommendation: AirOps for building AI content workflows that generate SEO-optimized content at scale.

AI Search

AI-powered web search APIs built for LLMs and agents. Return structured results with on-demand text, highlights, and summaries.

Agent recommendation: Exa for neural search over the open web — content research, competitor/similar-page discovery, link prospecting, news monitoring, and audience research. Pairs well with seo-audit, content-strategy, and competitor-profiling skills.

Partner Ecosystem

Partner data sharing, co-sell, and ecosystem management.

Agent recommendation: Crossbeam for identifying partner account overlaps and co-sell opportunities. Introw for full partner relationship management — partner pipeline, commissions, tasks, and automated business review prep.

Email Outreach

Cold email outreach and email finding tools for link building and sales prospecting.

Agent recommendation: Hunter for finding emails. Lemlist or Instantly for sending cold email campaigns. Snov for combined finding + outreach.

Data Aggregation

Marketing data pipeline tools that connect multiple platforms for unified reporting.

Agent recommendation: Supermetrics for pulling data from multiple marketing platforms into unified reports. Coupler.io for automated data flows to spreadsheets and BI tools.

Commerce & CMS

E-commerce platforms and content management systems.

Agent recommendation: Shopify for e-commerce. Webflow for marketing sites. WordPress for blogs. For headless CMS: Sanity for developer-flexible content, Contentful for enterprise multi-locale, Strapi for self-hosted/budget-conscious. See headless CMS guide (../skills/content-strategy/references/headless-cms.md) for selection criteria.

---

CLI Tools

Zero-dependency, single-file Node.js CLIs for tools that don't ship their own. See clis/README.md for install instructions and usage.

All CLIs follow a consistent pattern:

• No dependencies — Node 18+ only, uses native fetch
• JSON output — pipe to jq, save to file, or use in scripts
• Env var auth — set {TOOL}_API_KEY and go
• Consistent commands — {tool} <resource> <action> [options]

---

MCP-Enabled Tools

These tools have Model Context Protocol servers available, enabling direct agent interaction:

• ga4 - Google Analytics 4 data access
• stripe - Payment and subscription management
• mailchimp - Email campaign management
• google-ads - Ad campaign management
• resend - Transactional email sending
• zapier - Workflow automation + SDK for 8,000+ app integrations
• zoominfo - B2B contacts and intent data
• clay - Data enrichment and outbound automation
• supermetrics - Cross-platform marketing data
• coupler - Marketing data pipelines
• outreach - Sales engagement sequences
• crossbeam - Partner ecosystem data
• introw - Partner relationship management
• exa - AI-powered web search for LLMs and agents

To use MCP tools, ensure the appropriate MCP server is configured in your environment.

Composio Integration

Composio (integrations/composio.md) provides managed OAuth and pre-built connectors for 500+ tools via a single MCP server. It adds MCP access to tools that don't have native MCP servers, including HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, Notion, and more.

• Setup: npx @composio/mcp@latest setup
• Quick start: See tools/composio/README.md (composio/README.md)
• Marketing tool mapping: See tools/composio/marketing-tools.md (composio/marketing-tools.md)

Use Composio when you need MCP access to OAuth-heavy tools. Prefer native MCP servers (GA4, Stripe, Mailchimp, etc.) when available — they have deeper coverage.

Cogny Integration

Cogny (integrations/cogny.md) is a hosted MCP gateway focused on marketing channels — one federated MCP URL with managed OAuth across every channel you've connected. Narrower than Composio (marketing-only) and useful when you want SEO, paid social, and privacy-friendly analytics behind a single MCP login.

• Setup: connect channels at cogny.com (https://cogny.com), then in Claude.ai go to Settings → Connectors → Add custom connector and paste https://app.cogny.com/mcp
• Channels: Search Console, Bing Webmaster, Semrush, LinkedIn Ads, Reddit Ads, TikTok Ads, Plausible, Fathom
• Pricing: Solo plan starts at $9/mo (7-day trial)

Use Cogny when you only need marketing channels and want to avoid running your own OAuth proxy. Prefer native APIs when you need deep, custom control of a single tool.

---

Quick Start by Use Case

Setting up analytics tracking

1. Read ga4.md (integrations/ga4.md) for web analytics
2. Read segment.md (integrations/segment.md) if routing to multiple tools

Launching a referral program

1. Read rewardful.md (integrations/rewardful.md) or tolt.md (integrations/tolt.md) for Stripe-based programs
2. Read dub-co.md (integrations/dub-co.md) for link tracking

Setting up email automation

1. Read customer-io.md (integrations/customer-io.md) for behavior-based automation
2. Read resend.md (integrations/resend.md) for transactional email

Running email outreach for backlinks

1. Read hunter.md (integrations/hunter.md) for finding emails
2. Read lemlist.md (integrations/lemlist.md) or instantly.md (integrations/instantly.md) for sending campaigns

Running paid ads

1. Read google-ads.md (integrations/google-ads.md) for search campaigns
2. Read meta-ads.md (integrations/meta-ads.md) for social campaigns

---

Supporting file: tools/integrations/apollo.md

Apollo.io

B2B prospecting and data enrichment platform with 210M+ contacts and 35M+ companies for sales intelligence.

Capabilities

Authentication

• Type: API Key
• Header: x-api-key: {api_key} or Authorization: Bearer {token}
• Get key: Settings > Integrations > API at https://app.apollo.io

Common Agent Operations

People Search

POST https://api.apollo.io/api/v1/mixed_people/api_search

{
  "person_titles": ["Sales Manager"],
  "person_locations": ["United States"],
  "organization_num_employees_ranges": ["1,100"],
  "page": 1
}

Person Enrichment

POST https://api.apollo.io/api/v1/people/match

{
  "first_name": "Tim",
  "last_name": "Zheng",
  "domain": "apollo.io"
}

Bulk People Enrichment

POST https://api.apollo.io/api/v1/people/bulk_match

{
  "details": [
    { "email": "tim@apollo.io" },
    { "first_name": "Jane", "last_name": "Doe", "domain": "example.com" }
  ]
}

Organization Search

POST https://api.apollo.io/api/v1/mixed_companies/search

{
  "organization_locations": ["United States"],
  "organization_num_employees_ranges": ["1,100"],
  "page": 1
}

Organization Enrichment

POST https://api.apollo.io/api/v1/organizations/enrich

{
  "domain": "apollo.io"
}

Key Metrics

Person Data

• first_name, last_name - Name
• title - Job title
• email - Verified email
• linkedin_url - LinkedIn profile
• organization - Company details
• seniority - Seniority level
• departments - Department list

Organization Data

• name - Company name
• website_url - Website
• estimated_num_employees - Employee count
• industry - Industry
• annual_revenue - Revenue
• technologies - Tech stack
• funding_total - Total funding

Parameters

People Search

• person_titles - Array of job titles
• person_locations - Array of locations
• person_seniorities - Array: owner, founder, c_suite, partner, vp, head, director, manager, senior, entry
• organization_num_employees_ranges - Array of ranges (e.g., "1,100")
• organization_ids - Filter by Apollo org IDs
• page - Page number (default: 1)
• per_page - Results per page (default: 25, max: 100)

Person Enrichment

• email - Email address
• first_name + last_name + domain - Alternative lookup
• linkedin_url - LinkedIn URL
• reveal_personal_emails - Include personal emails
• reveal_phone_number - Include phone numbers

Organization Search

• organization_locations - Array of locations
• organization_num_employees_ranges - Employee count ranges
• organization_ids - Specific org IDs
• page - Page number

When to Use

• Building targeted prospect lists by role, seniority, and company size
• Enriching leads with verified contact info
• Finding decision-makers at target accounts
• Company research and firmographic analysis
• ABM campaign targeting
• Sales intelligence and outbound prospecting

Rate Limits

• Rate limits vary by plan
• Standard: 100 requests/minute for most endpoints
• Bulk enrichment: up to 10 people per request
• Search: max 50,000 records (100 per page, 500 pages)

Relevant Skills

• abm-strategy
• lead-enrichment
• lead-scoring
• cold-email
• competitors

---

Supporting file: tools/integrations/browserbase.md

Browserbase

Headless browser as a service. Spin up real Chromium browsers via API, drive them with Playwright/Puppeteer, get full session recordings. Useful when a target site requires JS rendering, user interaction, or session state that simple HTTP fetches can't handle.

Capabilities

Authentication

• Type: API Key
• Header: x-bb-api-key: YOUR_API_KEY
• Get key: https://www.browserbase.com/settings
• Env vars: BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID
• Base URL: https://api.browserbase.com

Core Operations

Create a browser session

POST https://api.browserbase.com/v1/sessions
x-bb-api-key: YOUR_API_KEY

{
  "projectId": "YOUR_PROJECT_ID"
}

Returns a session ID and a WebSocket URL (connectUrl) you connect to with Playwright or Puppeteer.

Connect with Playwright (Node)

import { chromium } from 'playwright-core';
import { Browserbase } from '@browserbasehq/sdk';

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY });
const session = await bb.sessions.create({ projectId: process.env.BROWSERBASE_PROJECT_ID });

const browser = await chromium.connectOverCDP(session.connectUrl);
const page = await browser.newPage();
await page.goto('https://joescoffeeshop.com');
const html = await page.content();
const title = await page.title();
await browser.close();

List session recordings

GET https://api.browserbase.com/v1/sessions/{sessionId}/logs

Useful for debugging when a scrape doesn't return what you expected — session recordings show exactly what the browser saw.

Stagehand (high-level AI-friendly wrapper)

Browserbase ships Stagehand (https://github.com/browserbase/stagehand), a Playwright wrapper with act(), extract(), and observe() methods that take natural-language instructions instead of CSS selectors. Stagehand also publishes an MCP server.

import { Stagehand } from '@browserbasehq/stagehand';

const stagehand = new Stagehand({ env: 'BROWSERBASE' });
await stagehand.init();
await stagehand.page.goto('https://joescoffeeshop.com');

const contact = await stagehand.page.extract({
  instruction: "Extract the business phone number, email, and street address",
  schema: { phone: 'string', email: 'string', address: 'string' }
});

When to Use (over Firecrawl)

• Site requires user interaction (cookie consent, age gate, click-through before content loads)
• Form submission to access a quote/contact page
• Session state matters (logged-in tools, multi-step flows)
• Complex JS rendering that even Firecrawl's headless option struggles with
• Want full session recordings for audit/debugging
• AI-driven scraping via Stagehand's natural-language extraction

For simple "scrape a page as markdown," Firecrawl is lower-overhead. Use Browserbase when you actually need the browser-as-a-service model.

When NOT to Use

Same hard rules as Firecrawl. Browserbase gives you a more powerful browser, which means the temptation to bypass anti-scraping defenses is higher. Don't:

• ✗ Bulk-scrape Google Maps / search results, LinkedIn, Yelp, or any platform whose ToS forbids it
• ✗ Bypass CAPTCHAs, login walls, or bot protections
• ✗ Auto-fill forms on platforms you don't have an account or legitimate access to

Use Browserbase for: individual public business sites the user has a URL for, where rendering or interaction is required.

Pricing

• Free tier: limited monthly minutes
• Paid tiers scale by browser minutes + concurrency
• Confirm at https://www.browserbase.com/pricing

Relevant Skills

• prospecting (programmatic site visits for prospect enrichment)
• competitor-profiling (when competitor sites need rendering or interaction)
• cro (page audits that need real browser state)
• analytics (testing tracking implementations end-to-end)

---

Supporting file: tools/integrations/clay.md

Clay

Data enrichment and outbound automation platform for building lead lists with waterfall enrichment across 75+ data providers.

Capabilities

Authentication

• Type: API Key (Bearer token)
• Header: Authorization: Bearer {api_key}
• Get key: Settings > API at https://app.clay.com

Common Agent Operations

List Tables

GET https://api.clay.com/v3/tables

Authorization: Bearer {api_key}

Get Table Details

GET https://api.clay.com/v3/tables/{table_id}

Authorization: Bearer {api_key}

Get Table Rows

GET https://api.clay.com/v3/tables/{table_id}/rows?page=1&per_page=25

Authorization: Bearer {api_key}

Add Row to Table

POST https://api.clay.com/v3/tables/{table_id}/rows

{
  "first_name": "Jane",
  "last_name": "Doe",
  "company": "Acme Inc",
  "email": "jane@acme.com"
}

People Enrichment

POST https://api.clay.com/v3/people/enrich

{
  "email": "jane@acme.com"
}

Company Enrichment

POST https://api.clay.com/v3/companies/enrich

{
  "domain": "acme.com"
}

Key Metrics

Person Data

• first_name, last_name - Name
• email - Email address
• title - Job title
• linkedin_url - LinkedIn profile
• company - Company name
• location - Location
• seniority - Seniority level

Company Data

• name - Company name
• domain - Website domain
• industry - Industry
• employee_count - Number of employees
• revenue - Estimated revenue
• location - Headquarters location
• technologies - Tech stack
• description - Company description

Table Data

• id - Table ID
• name - Table name
• row_count - Number of rows
• columns - Column definitions
• created_at - Creation timestamp
• updated_at - Last update timestamp

Parameters

Tables

• page - Page number (default: 1)
• per_page - Results per page (default: 25)

People Enrichment

• email - Email address
• linkedin_url - LinkedIn profile URL
• first_name + last_name - Name-based lookup

Company Enrichment

• domain - Company domain (e.g., "acme.com")

Add Row

• Fields are dynamic and match the table's column definitions
• Pass data as key-value pairs matching column names

When to Use

• Building enriched prospect lists with waterfall enrichment across multiple providers
• Enriching leads with person and company data from 75+ sources
• Automating outbound workflows with enriched data
• Finding verified contact info (emails, phone numbers, social profiles)
• Company research and firmographic analysis
• Triggering enrichment workflows via webhooks
• Syncing enriched data back to CRM or outbound tools

Rate Limits

• Rate limits vary by plan
• Standard: 100 requests/minute
• Enterprise plans have higher limits
• Enrichment credits consumed per lookup vary by data provider
• Webhook endpoints accept data continuously

Relevant Skills

• cold-email
• revops
• sales-enablement
• competitors

---

Supporting file: tools/integrations/clearbit.md

Clearbit (HubSpot Breeze Intelligence)

Company and person data enrichment API for converting leads with 100+ firmographic and technographic attributes.

Capabilities

Authentication

• Type: Bearer Token (or Basic Auth with API key as username)
• Header: Authorization: Bearer {api_key}
• Get key: https://dashboard.clearbit.com/api

Common Agent Operations

Person Enrichment (by email)

GET https://person.clearbit.com/v2/people/find?email=alex@clearbit.com

Returns 100+ attributes: name, title, company, location, social profiles, employment history.

Company Enrichment (by domain)

GET https://company.clearbit.com/v2/companies/find?domain=clearbit.com

Returns firmographics: industry, size, revenue, tech stack, location, funding.

Combined Enrichment (person + company)

GET https://person.clearbit.com/v2/combined/find?email=alex@clearbit.com

Returns both person and company data in a single request.

Reveal (IP to company)

GET https://reveal.clearbit.com/v1/companies/find?ip=104.132.0.0

Identifies the company behind a website visitor by IP address.

Name to Domain

GET https://company.clearbit.com/v1/domains/find?name=Clearbit

Converts a company name to its domain.

Prospector (find employees)

GET https://prospector.clearbit.com/v1/people/search?domain=clearbit.com&role=sales&seniority=executive

Finds employees at a company filtered by role, seniority, title.

API Pattern

Clearbit uses separate subdomains per API:

• person.clearbit.com - Person data
• company.clearbit.com - Company data, Name to Domain
• person-stream.clearbit.com - Streaming person lookup (blocking, up to 60s)
• company-stream.clearbit.com - Streaming company lookup (blocking, up to 60s)
• reveal.clearbit.com - IP to company
• prospector.clearbit.com - Employee search

Standard endpoints return 202 Accepted if data is being processed (use webhooks). Stream endpoints block until data is ready.

Key Metrics

Person Attributes

• name.fullName - Full name
• title - Job title
• role - Job role (sales, engineering, etc.)
• seniority - Seniority level
• employment.name - Company name
• linkedin.handle - LinkedIn profile

Company Attributes

• name - Company name
• domain - Website domain
• category.industry - Industry
• metrics.employees - Employee count
• metrics.estimatedAnnualRevenue - Revenue range
• tech - Technology stack array
• metrics.raised - Total funding raised

Parameters

Person Enrichment

• email (required) - Email address to look up
• webhook_url - URL for async results
• subscribe - Subscribe to future changes

Company Enrichment

• domain (required) - Company domain to look up
• webhook_url - URL for async results

Prospector

• domain (required) - Company domain
• role - Job role filter (sales, engineering, marketing, etc.)
• seniority - Seniority filter (executive, director, manager, etc.)
• title - Exact title filter
• page - Page number (default: 1)
• page_size - Results per page (default: 5, max: 20)

When to Use

• Lead scoring and qualification based on firmographic data
• Enriching CRM contacts with company and person data
• De-anonymizing website visitors with Reveal
• Building prospect lists with Prospector
• Personalizing marketing based on company attributes
• Routing leads based on company size, industry, or tech stack

Rate Limits

• Enrichment: 600 requests/minute
• Prospector: 100 requests/minute
• Reveal: 600 requests/minute
• Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers

Relevant Skills

• lead-scoring
• personalization
• abm-strategy
• lead-enrichment
• competitors

---

Supporting file: tools/integrations/firecrawl.md

Firecrawl

Web scraping API that turns single pages or full sites into clean LLM-ready markdown. Handles JS rendering, anti-bot defenses, and proxy rotation so you can extract structured data from individual public business sites.

Capabilities

Authentication

• Type: API Key
• Header: Authorization: Bearer fc-YOUR_API_KEY
• Get key: https://www.firecrawl.dev/app/api-keys
• Env var: FIRECRAWL_API_KEY
• Base URL: https://api.firecrawl.dev

Core Operations

Scrape a single page

POST https://api.firecrawl.dev/v1/scrape
Authorization: Bearer fc-YOUR_API_KEY

{
  "url": "https://joescoffeeshop.com",
  "formats": ["markdown", "html"]
}

Returns the page as clean markdown (LLM-ready, no nav cruft) plus optional raw HTML.

Map a site (discover all URLs)

POST https://api.firecrawl.dev/v1/map

{
  "url": "https://example.com",
  "limit": 100
}

Returns a list of URLs found on the site. Use this to identify key pages (/pricing, /about, /contact, /team) before scraping individually.

Crawl multiple pages

POST https://api.firecrawl.dev/v1/crawl

{
  "url": "https://example.com",
  "limit": 20,
  "scrapeOptions": {
    "formats": ["markdown"]
  }
}

Crawls multiple pages from a single site. Use sparingly — costs scale with pages. Set limit and includePaths to target specific URL patterns.

Extract structured data

POST https://api.firecrawl.dev/v1/extract

{
  "urls": ["https://joescoffeeshop.com"],
  "schema": {
    "phone": "string",
    "address": "string",
    "hours": "string",
    "email": "string"
  }
}

Returns data matching the schema — useful when you want consistent fields across many sites rather than raw markdown.

Search the web

POST https://api.firecrawl.dev/v1/search

{
  "query": "\"Joe's Coffee Shop\" Boulder Colorado",
  "limit": 10
}

Web search + scrape of top results. Useful for cross-source verification (find a business's official site when you only have a name + location).

MCP Tools (when used via MCP server)

When to Use

• Local SMB prospecting: verify a business's website status (live, weak, missing) at the URL level after manual Maps/Yelp discovery
• Single-target enrichment: pull contact info, hours, services from a business's own site
• Competitor research: scrape competitor pricing, features, customer pages (this is the primary use in competitor-profiling skill)
• Programmatic page extraction: when you need many sites' homepages or about pages in a consistent format
• JS-heavy sites: when the page won't render with a simple curl because content loads after page load

When NOT to Use

Critical — do not use Firecrawl to scrape platforms hosting prospects:

• ✗ Google Maps / Google search results — Google ToS prohibits bulk extraction
• ✗ LinkedIn — explicit ToS violation, will get scraper accounts banned and risks legal exposure
• ✗ Yelp — ToS prohibits commercial scraping
• ✗ Apollo / ZoomInfo / Clearbit listings — their ToS prohibits using competing data extracts
• ✗ Any platform you don't have a legitimate basis to extract from at scale

Use Firecrawl for: the business's own website (which you found via manual discovery on those platforms). That's the line — discovery happens on platforms, extraction happens on individual public business sites.

Pricing

• Free tier: limited monthly credits
• Paid tiers scale by request volume + concurrency
• Confirm at https://www.firecrawl.dev/pricing

Rate Limits

• Default: tier-dependent (typically 5–20 concurrent requests on paid plans)
• Per-page cost varies by content type and rendering needs

Relevant Skills

• prospecting (site enrichment for individual business URLs)
• competitor-profiling (primary use: full-site competitor analysis)
• ai-seo (scrape your own content for AI search optimization)
• content-strategy (scrape industry sites for content gap analysis)

---

Supporting file: tools/integrations/github.md

GitHub

GitHub REST API for prospecting use cases: listing users who star, fork, or watch a repo as a high-quality developer-intent signal.

Capabilities

Authentication

• Type: Personal Access Token (PAT) or Fine-Grained PAT
• Header: Authorization: Bearer {token}
• Get token: https://github.com/settings/tokens
• Scopes for prospecting:
  • Public data (stargazers, forks, public profiles): no scope required with a token, or unauthenticated
  • Public repo metadata: public_repo scope
• Env var: GITHUB_TOKEN

Rate limits

A 1,000-star repo with full enrichment (1 list call + 1 profile call per user) = ~1,011 requests. Always set a token.

Common Agent Operations

List stargazers (users who starred a repo)

GET https://api.github.com/repos/{owner}/{repo}/stargazers?per_page=100&page=1

Accept: application/vnd.github+json
X-GitHub-Api-Version: 2022-11-28
Authorization: Bearer {token}

Pagination via Link header (rel="next", rel="last"). Default 30 per page, max 100.

Returns array of user objects with login, id, html_url, type (User or Organization). Full profile fields (email, company, blog, bio, location) require a follow-up call per user.

List forks (gives fork owner profiles)

GET https://api.github.com/repos/{owner}/{repo}/forks?per_page=100&page=1

Each fork object includes the owner (the user/org that forked). Forks are a stronger signal than stars — they imply intent to modify, not just bookmark.

List watchers (subscribers)

GET https://api.github.com/repos/{owner}/{repo}/subscribers?per_page=100&page=1

GitHub's "watch" → API's "subscribers". Smaller pool than stargazers but signals deeper engagement.

Get user profile (enrichment)

GET https://api.github.com/users/{username}

Returns: name, company, blog, email (if public), bio, twitter_username, location, public_repos, followers, created_at, hireable.

Key fields for prospecting:

• email: only ~5–20% of users publish this. Always nullable.
• company: many users include @org syntax — strip the @ for plain company name.
• blog: often a personal website where contact info is published.
• twitter_username / bio: useful for cross-channel research.

Check rate limit

GET https://api.github.com/rate_limit

Prospecting Workflows

Workflow 1 — Stargazers of a competitor or adjacent tool

# 100 stargazers, enrich each one, only keep those with email or company set
node tools/clis/github-prospects.js stargazers vercel/next.js \
  --limit 100 --enrich --format csv > nextjs-stars.csv

Filter the CSV in your spreadsheet by company set OR email set OR blog set. Hand off to Apollo/Clay/Hunter to enrich the rest with email-by-name+company.

Workflow 2 — Forks of your own repo (warm intent)

People who fork your repo have already shown direct interest. High-conversion outreach prospects.

node tools/clis/github-prospects.js forks yourorg/yourrepo \
  --enrich --with-email --format csv > my-fork-prospects.csv

Workflow 3 — Watchers of a category-defining repo

Watchers are smaller in number but higher in intent — they're tracking changes, not just bookmarking.

node tools/clis/github-prospects.js watchers tldraw/tldraw \
  --enrich --with-company --format csv > tldraw-watchers.csv

CLI Reference

# Stargazers
node tools/clis/github-prospects.js stargazers <owner/repo> \
  [--limit N] [--enrich] [--with-email] [--with-company] \
  [--with-blog] [--type User|Organization] [--format csv|json]

# Forks
node tools/clis/github-prospects.js forks <owner/repo> [...same flags]

# Watchers (subscribers in API terms)
node tools/clis/github-prospects.js watchers <owner/repo> [...same flags]

# Single user lookup
node tools/clis/github-prospects.js user <username>

# Check rate limit
node tools/clis/github-prospects.js rate-limit

Flags:

• --limit N: cap total results pulled from the list endpoint
• --target N: when filtering with --with-*, stop enriching as soon as N users match (saves quota on restrictive filters)
• --enrich: fetch full profile per user (1 extra request each)
• --with-email / --with-company / --with-blog: filter to users with these fields set (implies --enrich)
• --type User|Organization: filter by account type
• --format csv: output prospecting-ready CSV; default is JSON
• --dry-run: preview the request without sending

When to Use

• SaaS prospecting (primary use case): stargazers of a competitor, complement, or category-defining repo as in-market developer signal
• Open-source product marketing: see who's forking or watching your own repo for warm outreach
• Developer-tool ICP discovery: stargazers of next.js, prisma, tailwindcss, etc., signal a Next.js / Prisma / Tailwind developer
• Trigger event monitoring: a recent fork of a competitor's repo often signals dissatisfaction or active evaluation

When NOT to Use

• Email is your only signal you need — GitHub yields email for only ~5–20% of users. Pair with Apollo, Clay, or Hunter for enrichment from name + company.
• Hyper-broad lists — a repo with 100K+ stars is mostly noise. Smaller, more specific repos (5K–25K stars) give higher-signal lists.
• You don't have a way to handle high-volume LinkedIn lookup downstream — most enrichment from GitHub username goes through LinkedIn Sales Nav manually.

Compliance Notes

• GitHub data is public — no ToS issue with reading the API. The ToS prohibits abusive scraping (bypassing rate limits, mass account creation), not legitimate API usage.
• Personal emails published on GitHub — users opt in to publishing their email. Treat as business contact when paired with company/blog signals; respect GDPR/CAN-SPAM for the downstream send.
• Source URL lineage — for every prospect added from GitHub, capture html_url (their profile URL) and the source repo. Required for GDPR DSAR defense.
• Cool-down between large pulls — even at 5,000 req/hr, don't burst-fingerprint. Pagination is naturally paced; respect X-RateLimit-Remaining headers.

Pairing with Other Tools

Typical GitHub prospecting pipeline:

1. Pull stargazers/forkers via this CLI
2. Filter to users with company set (or other signal)
3. Enrich missing emails via Apollo / Clay / Hunter (lookup by name + company domain)
4. Validate emails via Truelist before adding to outreach list
5. Hand off to cold-email skill for outreach

See skills/prospecting/references/saas-prospecting.md and data-sources.md for the full prospecting framework.

Relevant Skills

• prospecting (primary use case)
• cold-email (downstream outreach)
• competitor-profiling (deeper account-level research on individual stargazers worth pursuing)

---

Supporting file: tools/integrations/hunter.md

Hunter.io

Email finding and verification platform for outreach and link building.

Capabilities

Authentication

• Type: API Key (query parameter)
• Parameter: api_key={key}
• Env var: HUNTER_API_KEY
• Get key: Hunter dashboard > API (https://hunter.io/api-keys)

Common Agent Operations

Find emails for a domain

node tools/clis/hunter.js domain search --domain example.com --limit 10

Find a specific person's email

node tools/clis/hunter.js email find --domain example.com --first-name John --last-name Doe

Verify an email address

node tools/clis/hunter.js email verify --email john@example.com

Count emails available for a domain

node tools/clis/hunter.js domain count --domain example.com

Manage leads

# List leads
node tools/clis/hunter.js leads list --limit 20

# Create a lead
node tools/clis/hunter.js leads create --email john@example.com --first-name John --last-name Doe --company "Example Inc"

# Delete a lead
node tools/clis/hunter.js leads delete --id 12345

Manage campaigns

# List campaigns
node tools/clis/hunter.js campaigns list

# Get campaign details
node tools/clis/hunter.js campaigns get --id 12345

# Start/pause a campaign
node tools/clis/hunter.js campaigns start --id 12345
node tools/clis/hunter.js campaigns pause --id 12345

Check account usage

node tools/clis/hunter.js account info

Rate Limits

• Free plan: 25 searches/month, 50 verifications/month
• Paid plans scale with tier
• API rate limit: 10 requests/second

Use Cases

• Link building: Find email contacts at target domains for outreach
• Prospecting: Build lead lists from company domains
• Verification: Clean email lists before sending campaigns

---

Supporting file: tools/integrations/outreach.md

Outreach

Sales engagement platform for managing prospects, sequences, and outbound campaigns at scale.

Capabilities

Authentication

• Type: OAuth2 Bearer Token
• Header: Authorization: Bearer {access_token}
• Content-Type: application/vnd.api+json
• Get token: Settings > API at https://app.outreach.io or via OAuth2 flow

Common Agent Operations

List Prospects

curl -s https://api.outreach.io/api/v2/prospects \
  -H "Authorization: Bearer $OUTREACH_ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json"

Get a Prospect

curl -s https://api.outreach.io/api/v2/prospects/42 \
  -H "Authorization: Bearer $OUTREACH_ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json"

Create a Prospect

curl -s -X POST https://api.outreach.io/api/v2/prospects \
  -H "Authorization: Bearer $OUTREACH_ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "prospect",
      "attributes": {
        "emails": ["jane@example.com"],
        "firstName": "Jane",
        "lastName": "Doe"
      }
    }
  }'

List Sequences

curl -s https://api.outreach.io/api/v2/sequences \
  -H "Authorization: Bearer $OUTREACH_ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json"

Add Prospect to Sequence

curl -s -X POST https://api.outreach.io/api/v2/sequenceStates \
  -H "Authorization: Bearer $OUTREACH_ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "sequenceState",
      "relationships": {
        "prospect": { "data": { "type": "prospect", "id": 42 } },
        "sequence": { "data": { "type": "sequence", "id": 7 } }
      }
    }
  }'

List Mailings for a Sequence

curl -s "https://api.outreach.io/api/v2/mailings?filter[sequence][id]=7" \
  -H "Authorization: Bearer $OUTREACH_ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json"

List Accounts

curl -s https://api.outreach.io/api/v2/accounts \
  -H "Authorization: Bearer $OUTREACH_ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json"

List Tasks

curl -s "https://api.outreach.io/api/v2/tasks?filter[status]=incomplete" \
  -H "Authorization: Bearer $OUTREACH_ACCESS_TOKEN" \
  -H "Content-Type: application/vnd.api+json"

Key Metrics

Prospect Data

• firstName, lastName - Name
• emails - Email addresses
• title - Job title
• company - Company name
• tags - Prospect tags
• engagedAt - Last engagement timestamp

Sequence Data

• name - Sequence name
• enabled - Whether sequence is active
• sequenceType - Type (e.g., interval, date-based)
• stepCount - Number of steps
• openCount, clickCount, replyCount - Engagement metrics

Mailing Data

• mailingType - Type of mailing
• state - Delivery state
• openCount, clickCount - Engagement
• deliveredAt, openedAt, clickedAt - Timestamps

Parameters

Prospects

• page[number] - Page number (default: 1)
• page[size] - Results per page (default: 25, max: 1000)
• filter[emails] - Filter by email
• filter[firstName] - Filter by first name
• filter[lastName] - Filter by last name
• sort - Sort field (e.g., createdAt, -updatedAt)

Sequences

• filter[name] - Filter by sequence name
• filter[enabled] - Filter by active status

Mailings

• filter[sequence][id] - Filter by sequence ID
• filter[prospect][id] - Filter by prospect ID

Tasks

• filter[status] - Filter by status (e.g., incomplete, complete)
• filter[taskType] - Filter by type (e.g., call, email, action_item)

When to Use

• Managing outbound sales sequences and cadences
• Adding prospects to automated email sequences
• Tracking prospect engagement across touchpoints
• Managing sales tasks and follow-ups
• Coordinating multi-channel outreach campaigns
• Monitoring sequence performance and reply rates

Rate Limits

• 10,000 requests per hour per user
• Burst limit: 100 requests per 10 seconds
• Rate limit headers returned: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• 429 responses when limits exceeded

Relevant Skills

• cold-email
• revops
• sales-enablement
• emails

---

Supporting file: tools/integrations/rb2b.md

RB2B

Website visitor identification platform that de-anonymizes B2B website traffic, revealing the individual people visiting your site with LinkedIn profiles, emails, and company data.

Capabilities

Most teams use RB2B via its native integrations (Slack, CRM push, Zapier, webhooks) rather than direct API access. A separate API Partner Program (https://www.rb2b.com/apis) exists for programmatic access.

Authentication

• Type: Native integrations (no API key needed for standard use)
• API Partner Program: Separate credentials via https://www.rb2b.com/apis
• Free tier: Limited credits/month with Slack alerts

Pricing Tiers

Pricing changes frequently — verify at https://www.rb2b.com/pricing.

Key Integrations

RB2B pushes identified visitor data to 50+ tools:

• CRM: Salesforce, HubSpot
• Outreach: Instantly, HeyReach, Lemlist
• Enrichment: Clay, Apollo, Clearbit
• Automation: Zapier, Make
• Alerts: Slack (real-time notifications)

What RB2B Reveals Per Visitor

• Full name and LinkedIn profile URL
• Job title and company
• Validated business email (Pro+)
• Pages visited and visit duration
• Number of visits and return frequency
• Company data (size, industry, location)

Common Agent Operations

Real-Time Visitor Alerts

Configure Slack alerts for high-intent visitors:

• Visitors who hit pricing page
• Visitors who return 3+ times
• Visitors from target account list
• Visitors matching ICP job titles

Visitor-to-Outreach Pipeline

1. RB2B identifies visitor with LinkedIn + email
2. Filter by ICP criteria (title, company size, pages visited)
3. Route to outreach tool (Instantly, Lemlist) or CRM (HubSpot, Salesforce)
4. Trigger personalized cold email referencing pages they visited

Intent Scoring

Score visitors by behavior signals:

• High intent: Pricing page, demo page, comparison pages, 3+ visits
• Medium intent: Feature pages, case studies, 2 visits
• Low intent: Blog only, single visit, bounced quickly

Suppression Lists

Prevent outreach to:

• Existing customers (match against CRM)
• Active deals in pipeline
• Competitors and agencies
• Recently contacted prospects

When to Use

• Identifying anonymous website visitors for sales outreach
• Building ABM (account-based marketing) target lists from site traffic
• Understanding which companies are researching your product
• Triggering personalized outreach based on page-level intent signals
• Feeding enrichment tools (Clay, Apollo) with warm visitor data

Limitations

• Person-level identification works best for US B2B traffic
• Not all visitors can be identified (typical match rates: 15-30%)
• Requires sufficient website traffic to be cost-effective
• Privacy considerations — ensure compliance with applicable regulations
• Free tier limited to Slack alerts (no CRM push or email export)

Relevant Skills

• cold-email
• revops
• customer-research
• ads

Sources

• RB2B pricing (https://www.rb2b.com/pricing)
• RB2B plans comparison (https://support.rb2b.com/en/articles/9173659-rb2b-plans-side-by-side-comparisons)
• RB2B API Partner Program (https://support.rb2b.com/en/articles/12579420-rb2b-apis-rb2b-s-api-partner-program)

---

Supporting file: tools/integrations/snov.md

Snov.io

Email finding, verification, and drip campaign platform for outreach.

Capabilities

Authentication

• Type: OAuth2 client credentials
• Flow: POST to /oauth/access_token with client_id + client_secret
• Env vars: SNOV_CLIENT_ID, SNOV_CLIENT_SECRET
• Get keys: Snov.io > Integration > API (https://app.snov.io/integration/api)

The CLI handles token acquisition automatically.

Common Agent Operations

Search emails by domain

node tools/clis/snov.js domain search --domain example.com --type all --limit 10

Find a specific person's email

node tools/clis/snov.js email find --domain example.com --first-name John --last-name Doe

Verify an email

node tools/clis/snov.js email verify --email john@example.com

Find prospect by email

node tools/clis/snov.js prospect find --email john@example.com

Add prospect to a list

node tools/clis/snov.js prospect add --email john@example.com --first-name John --last-name Doe --list-id 12345

Manage prospect lists

# List all lists
node tools/clis/snov.js lists list

# Get prospects in a list
node tools/clis/snov.js lists prospects --id 12345 --page 1 --per-page 50

Check domain technology stack

node tools/clis/snov.js technology check --domain example.com

Manage drip campaigns

# List campaigns
node tools/clis/snov.js drips list

# Get campaign details
node tools/clis/snov.js drips get --id 12345

# Add prospect to drip campaign
node tools/clis/snov.js drips add-prospect --id 12345 --email john@example.com

Rate Limits

• Rate limits vary by plan
• OAuth tokens expire after a set period; CLI handles refresh automatically

Use Cases

• Link building: Find contacts and run automated drip outreach
• Prospecting: Build and manage prospect lists
• Technology research: Check what tech stack a target domain uses
• Email verification: Clean lists before sending

---

Supporting file: tools/integrations/truelist.md

Truelist

Email verification and deliverability validation. Validates single emails synchronously or bulk lists asynchronously. Returns an email_state + email_sub_state plus rich metadata (domain, MX record, suggested correction, disposable/role classification).

Spec source: Truelist-Labs/truelist-openapi (https://github.com/Truelist-Labs/truelist-openapi) (OpenAPI 3.1).

Capabilities

Authentication

• Type: Bearer token (API key)
• Header: Authorization: Bearer YOUR_API_KEY
• Get key: https://truelist.io/settings/api-keys
• Base URL: https://api.truelist.io

Common Agent Operations

Verify a single email (synchronous)

POST https://api.truelist.io/api/v1/verify_inline?email=user@example.com
Authorization: Bearer YOUR_API_KEY

No request body — the email is a query parameter. Returns a single-element emails array with verification fields:

{
  "emails": [
    {
      "address": "user@example.com",
      "domain": "example.com",
      "canonical": "user@example.com",
      "mx_record": null,
      "first_name": null,
      "last_name": null,
      "email_state": "ok",
      "email_sub_state": "email_ok",
      "verified_at": "2026-02-21T10:39:12.570Z",
      "did_you_mean": null
    }
  ]
}

Bulk verification (asynchronous)

POST https://api.truelist.io/api/v1/verify
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "emails": [
    "user1@example.com",
    "user2@example.com"
  ]
}

Processes the list in the background. The response acknowledges submission; results are available via the dashboard, the Truelist UI's CSV download, or via integrations (Mailchimp, Klaviyo, HubSpot, Zapier, Make, n8n, etc.).

For large lists, the dashboard's CSV upload + download flow is typically the lowest-friction path.

Get account information

GET https://api.truelist.io/me
Authorization: Bearer YOUR_API_KEY

Returns email, name, UUID, time zone, admin role, API keys, and account plan info.

Response Fields (per email)

email_state values

email_sub_state values

Pair the two: email_state: ok + email_sub_state: is_role means "deliverable but a role inbox," whereas email_state: email_invalid + email_sub_state: failed_smtp_check means "doesn't exist."

Rate Limits

A 429 is returned on rate-limit exceed. Note: the per-email validation rate is separate and depends on your plan.

Error Responses

All error bodies follow {"error": "<human-readable message>"}.

When to Use

• Before adding contacts to any cold outreach list — non-negotiable safety step. Apollo/ZoomInfo/Hunter data accuracy is typically 60–80%; Truelist catches the rest.
• Real-time form validation — block disposable / typo'd emails at signup. Use the inline endpoint (or the form validation widget (https://truelist.io/docs/form-validation-widget)).
• Periodic list hygiene — re-verify your active list quarterly to remove bounces before they hurt sender reputation.
• Pre-import validation on email platform imports (Mailchimp, Klaviyo, HubSpot, etc.) — direct integrations exist for most.
• AI agent workflows via the official MCP server for Claude, Cursor, and VS Code.

Why This Step is Non-Negotiable

Cold email reputation is built over months and destroyed in days. ISPs (Gmail, Outlook, etc.) track sender reputation through:

• Bounce rate — bounces over 2% trigger throttling
• Spam complaints — spam traps in unvalidated lists generate complaints
• Engagement — sending to dead mailboxes hurts engagement metrics

A single unvalidated send to a bought or scraped list can damage a domain's sending reputation for months.

Workflow Integration

Typical prospecting flow:

1. Build initial prospect list (Apollo, Clay, ZoomInfo, Hunter, GitHub stargazers, etc.)
2. For agent-driven workflows: use the Truelist MCP server to validate inline as the agent builds the list
3. For programmatic workflows: POST emails to /api/v1/verify for async bulk OR /api/v1/verify_inline for sync single
4. For one-offs: CSV upload via dashboard, download annotated CSV
5. Filter: keep email_state: ok, include risky/accept_all cautiously with a strategy, exclude email_invalid, re-verify unknown
6. Hand cleaned list to outreach platform (Instantly, Lemlist, Outreach, etc.) — see outreach.md, instantly.md, lemlist.md

Native Integrations (no API code required)

For non-developer workflows, Truelist has direct integrations:

• Email platforms: Mailchimp, Klaviyo, HubSpot, ActiveCampaign, Brevo, Constant Contact, ConvertKit, Drip
• Automation: Zapier, Make.com, n8n
• CRM / sales: Salesforce, Go High Level, Clay.com
• Ecom: BigCommerce
• AI / agents: MCP server (Claude, Cursor, VS Code)

See https://truelist.io/integrations for the current list.

Relevant Skills

• prospecting (primary use case — validate before adding to outreach lists)
• cold-email (downstream outreach against the validated list)
• emails (transactional senders + subscriber list hygiene)
• popups (real-time form validation on opt-in capture)

---

Supporting file: tools/integrations/zoominfo.md

ZoomInfo

B2B contact database and intent data platform with 100M+ business contacts and company intelligence for sales and marketing teams.

Capabilities

Authentication

• Type: JWT Token (Bearer)
• Flow: POST /authenticate with username + password, receive JWT token
• Header: Authorization: Bearer {jwt_token}
• Env vars: ZOOMINFO_USERNAME + ZOOMINFO_PRIVATE_KEY or ZOOMINFO_ACCESS_TOKEN
• Get credentials: Contact ZoomInfo sales or admin portal at https://app.zoominfo.com

Common Agent Operations

Authenticate

POST https://api.zoominfo.com/authenticate

{
  "username": "user@company.com",
  "password": "private-key-here"
}

Contact Search

POST https://api.zoominfo.com/search/contact

{
  "jobTitle": ["VP Marketing"],
  "companyName": ["Acme Corp"],
  "managementLevel": ["VP"],
  "rpp": 25,
  "page": 1
}

Contact Enrichment

POST https://api.zoominfo.com/enrich/contact

{
  "matchEmail": ["jane@acme.com"]
}

Company Search

POST https://api.zoominfo.com/search/company

{
  "companyName": ["Acme"],
  "industry": ["Software"],
  "employeeCountMin": 50,
  "revenueMin": 10000000,
  "rpp": 25,
  "page": 1
}

Company Enrichment

POST https://api.zoominfo.com/enrich/company

{
  "matchCompanyWebsite": ["acme.com"]
}

Intent Data Lookup

POST https://api.zoominfo.com/lookup/intent

{
  "topicId": ["marketing-automation"],
  "companyId": ["123456"]
}

Scoops Lookup

POST https://api.zoominfo.com/lookup/scoops

{
  "companyId": ["123456"],
  "rpp": 25,
  "page": 1
}

Key Metrics

Contact Data

• firstName, lastName - Name
• jobTitle - Job title
• email - Verified email
• phone - Direct phone
• linkedinUrl - LinkedIn profile
• companyName - Company name
• managementLevel - Seniority level
• department - Department

Company Data

• companyName - Company name
• website - Website URL
• employeeCount - Employee count
• industry - Industry
• revenue - Annual revenue
• techStack - Technologies used
• fundingAmount - Total funding
• companyCity, companyState, companyCountry - Location

Intent Data

• topicName - Intent topic
• signalScore - Signal strength
• audienceStrength - Audience engagement level
• firstSeenDate, lastSeenDate - Signal timeframe

Parameters

Contact Search

• jobTitle - Array of job titles
• companyName - Array of company names
• managementLevel - Array: C-Level, VP, Director, Manager, Staff
• department - Array: Marketing, Sales, Engineering, Finance, etc.
• personLocationCity - Array of cities
• personLocationState - Array of states
• personLocationCountry - Array of countries
• rpp - Results per page (default: 25, max: 100)
• page - Page number (default: 1)

Contact Enrichment

• matchEmail - Array of email addresses
• personId - Array of ZoomInfo person IDs
• matchFirstName + matchLastName + matchCompanyName - Alternative lookup

Company Search

• companyName - Array of company names
• industry - Array of industries
• employeeCountMin / employeeCountMax - Employee count range
• revenueMin / revenueMax - Revenue range
• companyLocationCity - Array of cities
• rpp - Results per page
• page - Page number

Company Enrichment

• matchCompanyWebsite - Array of domains
• companyId - Array of ZoomInfo company IDs

Intent Data

• topicId - Array of intent topic IDs
• companyId - Array of company IDs

When to Use

• Identifying in-market accounts with intent signals
• Building targeted contact lists by role, seniority, and company
• Enriching leads with verified contact data and firmographics
• Finding decision-makers at target accounts for ABM
• Tracking company news and leadership changes via scoops
• Prioritizing outreach based on buyer intent signals

Rate Limits

• Rate limits vary by plan and endpoint
• Standard: ~200 requests/minute
• Bulk endpoints: batched requests recommended
• Authentication tokens expire after ~12 hours

Relevant Skills

• cold-email
• revops
• sales-enablement
• competitors