Waterfall Enrichment

---
name: waterfall-enrichment
description: "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."
version: "1.0.1"
compatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token
homepage: https://github.com/getcargohq/gtm-skills
metadata:
  author: getcargo
  source: one-off
  personas:
    - revops
    - gtm-engineering
  openclaw:
    requires:
      bins:
        - cargo-ai
    install:
      - kind: node
        package: "@cargo-ai/cli@latest"
        bins:
          - cargo-ai
    homepage: https://github.com/getcargohq/gtm-skills
---

# 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.

<!-- Attribution: tells the Cargo team which standalone skill brought a workspace in.
     Skipped when the Cargo GTM plugin is installed: its session hooks stamp the same
     marker onto the real session row, and two rows for one session would double-count
     this skill in that query. -->
```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 <uuid>` (2s interval) or
`cargo-ai orchestration batch get <uuid>` (5s).

## Example

> Run the 20 contacts in `event-leads.csv` through the waterfall and verify every email before I import them.

Illustrative output, fictional records:

| full_name | domain | email | provider | verified |
|---|---|---|---|---|
| Priya Raman | northwind.example | priya.raman@northwind.example | rung 1 | valid |
| Tomás Ferreira | fabrikam.example | tferreira@fabrikam.example | rung 3 | valid |
| Hannah Okafor | globex.example | h.okafor@globex.example | rung 2 | invalid |
| Wei Zhang | initech.example | | none | |

16 of 20 enriched and 14 verified deliverable, 4 left empty; 41.6 credits (20 × 2 + 16 × 0.1).

## 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.