# Playbook: Clay Enrichment Waterfall **School:** Signal-based / waterfall outbound, carried by Kareem Amin and Eric Nowoslawski (Clay lineage) and Guillaume Cabane's signal-triggering practice. Thesis: never send a bare list to a sequence — cascade a contact through cheap-to-expensive enrichment providers, let an AI agent research the account, and personalize outbound on the enriched fields rather than a generic template. **Deliverable type:** `integration-runbook` for the provider cascade, plus an `automation-spec` for the personalized-branch action that fires once enrichment completes. --- ## When to use this - Outbound to a definable account universe where public signals exist (job changes, funding events, tech-stack data, firmographic detail) — this is the Spear lane in Aaron Ross's Seeds/Nets/Spears classification. - You're feeding the outreach-operator role and want them working pre-researched contacts, not bare emails (§9.4 hand-off contract requires enrichment fields populated before a contact reaches that queue). - You have a cost budget per contact you need to respect — the waterfall's whole point is not paying for the expensive provider until the cheap one misses. ## When NOT to use this - Broad consumer audience with no firmographic signal surface (there's nothing meaningful to enrich — a personal email address doesn't have a "funding round"). - Inbound leads who already self-identified with rich form data — enrichment adds cost without adding information you don't already have; route straight to scoring instead. - No cost ceiling has been agreed — an unbounded waterfall against a large list can burn budget fast; this playbook requires a stated per-contact ceiling before it ships. --- ## Step-by-step build 1. **Order the provider cascade cheap → expensive.** E.g., free/low-cost email-verification and firmographic lookup first, mid-cost data enrichment second, expensive AI-research-agent (Claygent-style) last, reserved only for contacts that cleared the fit bar. 2. **Define stop-on-hit logic.** Once a required field is filled by a cheaper provider, skip the more expensive ones for that field — this is the entire cost-efficiency mechanism, not an optional nicety. 3. **State the cost ceiling per contact.** A hard number (e.g., "$0.75/contact max across the full cascade") — without this, the waterfall can silently become the most expensive step in the funnel. 4. **Build the field-mapping table.** Source field (per provider) → destination field on the customer-master record, with any transform noted (e.g., "provider returns `company_size_range`; map to internal `company_size_bucket` via lookup table"). 5. **Reference auth via env var / vault name only.** Every provider API key is a vault reference in the runbook — an inline key is a hard fail on this deliverable type (MANUAL §8.2/8.1). 6. **Define the dedupe rule.** What happens if the same contact is re-enriched from two entry points (e.g., re-appears in a second outbound list) — required field, not optional. 7. **State sync frequency/trigger.** Enrichment fires once, on first entry into the outbound pipeline, not on every sync — state this explicitly to avoid re-billing the same contact repeatedly. 8. **Write the failure/retry behavior and rollback.** What happens when a provider times out or returns malformed data — does the contact proceed with partial enrichment, or hold in a queue? State it. 9. **Wire the branch automation.** Once enrichment completes (or the waterfall exhausts with partial data), fire the automation-spec that hands the contact to outreach-operator with the enriched fields populated — this is the actual "then branch personalized outbound" step Amin/Nowoslawski's school is named for. ## Worked mini-example Cascade: (1) free email-verification API confirms deliverability and domain type — free, instant. (2) Mid-cost firmographic provider fills company size, industry, funding stage — stops here if a fit-disqualifying signal appears (e.g., company size < 5, below the marginal-cost cutoff — see Bult-Wansbeek in lead-scoring-routing). (3) AI research agent runs only on contacts that cleared step 2's fit bar, producing a 3-sentence account brief. Cost ceiling: $0.60/contact total. Field map: provider's `annual_revenue_range` → internal `revenue_bucket` (direct copy); provider's `funding_stage` → internal `signal_funding_recent` (transform: true if raised in last 12 months). Auth: all three provider keys referenced as `env.CLAY_API_KEY`, `env.FIRMO_API_KEY`, `env.CLAYGENT_API_KEY` — never inline. Dedupe: contact already enriched in the last 90 days skips the cascade and reuses cached fields. On completion, `lifecycle_stage` moves to "Enriched" and hands off to outreach-operator with the AI account brief attached to the task. ## How the verify gate applies The `integration-runbook` linter hard-fails on any inline secret matching a key/token pattern (must be an env var / vault reference), a missing field-mapping table, or an absent dedupe rule. It also requires the sync frequency/trigger and rollback procedure stated explicitly. The companion `automation-spec` for the branch action still needs its own EXIT condition (e.g., stop the enrichment-to-outreach chain if the contact unsubscribes mid-cascade) and idempotency note (don't re-enrich and re-bill on a duplicate webhook fire).