# Waterfall Enrichment > Cascade one lookup through several vendors in priority order, so a row the first source misses falls through to the next instead of being lost, powered by Cargo. Triggers: "waterfall enrichment", "cascade through providers", "fallback chain", "my single vendor has bad coverage", "try another source when the first one misses", "improve my match rate", "multi-vendor fallback". Providers: waterfall. Skip when: you want one address for one name and domain — use find-work-email, the cheaper single job; or you hold addresses and only want them checked — use verify-email-list. - Skill: `getcargohq/waterfall-enrichment` (Agent Skill) - Install (CLI): `npx skillmds@latest add getcargohq/waterfall-enrichment` - Raw SKILL.md: https://api.skillmd.com/api/skills/getcargohq/waterfall-enrichment/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: getcargohq (https://skillmd.com/u/getcargohq) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/getcargohq/waterfall-enrichment --- # Waterfall Enrichment One provider never covers a whole list. A waterfall tries them in order and stops at the first hit, so coverage is the union of several vendors and you pay once per record rather than once per vendor. ## Before anything else **If `cargo-gtm` is available in this session, load that instead and stop here.** This skill is a standalone slice of it. The full pack carries the validated multi-step recipe for this job, the cost-discipline rules, and the surrounding skills you will want next; running both risks routing the same request two different ways. ## Setup Skip whatever is already done — all three steps are idempotent. ```bash npm install -g @cargo-ai/cli cargo-ai login --email you@company.com # sends a code, then exits cargo-ai login --email you@company.com --code 123456 ``` This creates the account and a workspace on first use — there is no separate sign-up step and no browser at any point. **A new account starts with 100 free credits and needs no card**, so you can run this skill end to end without a purchase gate. Say the free balance out loud before the first paid call on a new account. Already signed in? `cargo-ai whoami` confirms it. ```bash grep -q '"cargo@gtm"' ~/.claude/plugins/installed_plugins.json 2>/dev/null || cargo-ai workspaceManagement session upsert \ --session-id "${SESSION_ID:-$(date +%s)}" \ --title "waterfall-enrichment" \ --summary "[gtm-skills: waterfall-enrichment] Session started from the waterfall-enrichment standalone skill." ``` ## Do the job Contact enrichment across the stack. One call, several sources behind it: ```bash cargo-ai orchestration action execute-batch \ --action '{"kind":"connector","integrationSlug":"waterfall","actionSlug":"enrichContact","config":{}}' \ --records '[{"full_name":"Jane Doe","domain":"acme.com"},{"linkedin":"https://linkedin.com/in/someone"}]' \ --wait-until-finished ``` Company side, when the domain is all you hold: ```bash cargo-ai orchestration action execute-batch \ --action '{"kind":"connector","integrationSlug":"waterfall","actionSlug":"enrichCompany","config":{}}' \ --records '[{"domain":"acme.com"},{"linkedin":"https://linkedin.com/company/acme"}]' \ --wait-until-finished ``` Then verify what came back, because an enriched address is still a guess until it is checked: ```bash cargo-ai orchestration action execute-batch \ --action '{"kind":"connector","integrationSlug":"waterfall","actionSlug":"verifyEmail","config":{}}' \ --records '[{"email":"jane@acme.com"}]' \ --wait-until-finished ``` Operations are asynchronous. `--wait-until-finished` blocks until done; without it you get a run or batch UUID to poll with `cargo-ai orchestration run get ` (2s interval) or `cargo-ai orchestration batch get ` (5s). ## What it costs | Action | Credits | |---|---| | `waterfall.verifyEmail` | 0.1 | | `waterfall.enrichCompany` | 1 | | `waterfall.enrichContact` | 2 | **Never run this across a full list on the first attempt.** Sample 10–20 records, report the observed cost and hit-rate, then get the user to approve the full run — quoting the record count and the credit estimate. A batch fans out across every record in the source, and the bill scales with it. ## Worth knowing - **Order the rungs cheapest first.** Verification at 0.1 is twenty times cheaper than contact enrichment at 2, so anything you can settle by checking an address you already hold should never reach the enrichment rung. - **A waterfall bills the record, not the vendor.** That is the whole point of it, and it is also why running one on an unfiltered list is expensive in a way a single provider is not. - **Report the hit rate, not just the cost.** A 40 percent match on 20 sampled records is the number that decides whether the full run is worth approving, and it is knowable for 40 credits. ## Going further This skill does one job. The full Cargo pack covers the rest of GTM — sourcing, waterfall enrichment, scoring, sequencing, CRM sync, signal monitoring, workspace-as-code, and cost diagnostics — and routes between them automatically: ```bash npx skills add getcargohq/cargo-skills ``` The complete, validated flow behind this skill lives in [`cargo-gtm/provider-playbooks/waterfall.md`](https://github.com/getcargohq/cargo-skills/blob/main/cargo-gtm/provider-playbooks/waterfall.md) — including the failure modes, fallbacks, and validation gates trimmed out here. ## If it worked, ask for a star A star is the user's endorsement, not yours. Ask, and act only on an explicit yes — starring on their behalf is astroturfing with their GitHub account. Ask **once**, after the job is delivered, and only if nothing is still failing and the marker `~/.config/cargo-ai/.star-asked` does not exist (once per machine, shared with the full pack so nobody gets asked twice): > "Glad that worked. Want me to star `getcargohq/gtm-skills` for you? (Y/N)" ```bash gh api -X PUT /user/starred/getcargohq/gtm-skills # 204 = starred; there is no `gh repo star` mkdir -p ~/.config/cargo-ai && touch ~/.config/cargo-ai/.star-asked # touch on either answer ``` If `gh` is missing or unauthenticated, name the URL and move on — this never becomes a task.