Ivx Ams Lead Dossier

Cursor install notes

• Skill root: this folder (scripts + references live here).
• Vendor source: ~/.cursor/skills/_vendor/ai-marketing-skills/ (git pull to update).
• Telemetry is optional; skip telemetry/*.py unless you opt in.
• Run Python from this skill directory so relative paths resolve.
• Prefer python on Windows if python3 is missing.

Lead Dossier Skill

Working directory

cd ~/.cursor/skills/ams-lead-dossier
# Windows: cd $env:USERPROFILE\.cursor\skills\ams-lead-dossier

Multi-source account research and lead enrichment pipeline for AI coding assistants.

Prerequisites

• Python 3.9+ with requests installed
• API keys configured as environment variables (see .env.example)
• Optional: CRM access for contact/company enrichment

Environment Variables

All API keys are configured via environment variables. Copy .env.example to .env:

Workflow 1: Account Research

Use when asked to research a company or build a prospect dossier.

Collect Parameters

Run Research

python3 scripts/account-researcher.py --domain acme.com --company "Acme Corp"

For batch research:

python3 scripts/account-researcher.py prospects.json

Results are cached for 7 days in data/account-research/.

Output Format

The engine produces a structured JSON dossier with:

• Website analysis (title, description, body snippet, marketing gaps)
• Tech stack (CRM, marketing tools, enterprise signals)
• Hiring signals (growth indicators)
• News/funding signals
• 3-5 sentence research brief

Workflow 2: Cascade Enrichment

Use when enriching a list of prospects with verified email addresses.

Prepare Config

Create data/enrichment-config.json:

{
  "email_validation_api_key": "YOUR_KEY",
  "email_validation_api_url": "https://api.your-provider.com/v1/people/email-finder",
  "email_validation_timeout_seconds": 10,
  "fallback_tag": "linkedin-outreach-only"
}

Run Enrichment

python3 scripts/cascade-enricher.py input.json output.json

Waterfall logic:

1. Has email from primary source? → Done
2. Try email finder API → Found? → Done
3. Has LinkedIn URL? → Tag as fallback
4. None → Tag as no-contact

Workflow 3: Full Lead Pipeline

Use when sourcing, verifying, and uploading leads end-to-end.

Collect Parameters

Run Pipeline

python3 scripts/lead-pipeline.py \
  --source-api-key "$LEAD_SOURCE_API_KEY" \
  --validation-api-key "$EMAIL_VALIDATION_API_KEY" \
  --campaign-api-key "$CAMPAIGN_TOOL_API_KEY" \
  --titles "VP Marketing,CMO,Head of Growth" \
  --industries "Marketing,Advertising" \
  --company-size "11,50" \
  --locations "United States" \
  --campaign-id "CAMPAIGN_UUID" \
  --volume 500 \
  --output-dir ./data/pipeline-runs/

Optional flags:

• --exclude-file /path/to/burned-emails.csv — additional exclusion list
• --dry-run — run everything except the final upload
• --keywords "SaaS,B2B" — additional search keywords

Review Output

Pipeline saves a JSON run log to the output directory with full stats:

• Sourced count, verification rate, dedup stats, upload results
• Complete list of leads processed

Workflow 4: Real-Time Lead Enrichment

Use for enriching inbound leads from webhooks, forms, or CRM triggers.

Run Enricher

python3 scripts/lead-enricher.py [--dry-run] [--backfill N]

The enricher:

1. Parses inbound lead data (website forms, voice agent calls, etc.)
2. Looks up contact and company in CRM
3. Runs account research for context
4. Builds an enriched lead card with all available data

Safety Rules

1. Never upload unverified leads — every email must pass validation
2. Always deduplicate — check existing contacts before uploading
3. Log everything — every run produces an auditable JSON log
4. Rate limit aware — built-in delays and exponential backoff
5. Idempotent — safe to re-run; duplicates are caught by dedup step
6. Security gates — scan all inbound web content before processing

Troubleshooting

• Search API returns no results: Check title/industry spelling; try broader criteria
• Email validation 429s: Script handles with backoff; if persistent, reduce volume
• Campaign tool silent failures: Some APIs silently block at high request rates; scripts include batch delays
• Cache stale: Delete files in data/account-research/ to force refresh