Waterfall enrichment: design for accepted data, not maximum matches

Updated November 7, 2026. An editorial engineering guide with hypothetical examples; no enrichment test was performed.

Waterfall enrichment attempts to resolve a missing field through successive data sources. A useful implementation stops when it has a result that meets a defined policy, rather than continuing to buy the same answer or accepting the first nonempty string. FullEnrich describes aggregating providers; Clay describes combining databases in a waterfall. Those are vendor descriptions of a method, not evidence that either product will outperform another on your records. API Overview - FullEnrich API Documentation Clay Waterfall: maximize your coverage of contact info | Clay.com

For a GTM operator, the practical question is whether the next source produces enough additional usable information to justify its cost and the complexity it adds. That requires a stable identity, a stop rule, and a ledger. Without those, a waterfall can turn a small data gap into repeated charges, contradictory records, and contact information nobody can explain.

Start by defining the accepted output

Write an acceptance contract before selecting providers. For example: "a work email for the same person and current employer, with an allowed verification state, checked within our freshness window, and no suppression restriction." This is a proposed policy, not a universal standard. A different use case may need company-level data or a phone number, with different review requirements.

Separate four events in the ledger: attempted, returned, billable, and accepted. They are not synonyms. FullEnrich's documentation bills one credit for a found work email in Deliverable, High Probability, or Catch-all states. A team may choose to accept only one of those states. Credits and Testing Tips - FullEnrich API Documentation

A buyer who budgets only for accepted records will underestimate spending whenever billable results are rejected. A buyer who counts all returned records as successes will overstate usefulness. Record both, and make the gap visible.

Provider order: optimize marginal value

Begin with your permitted, already-owned sources and a freshness check. If an approved value exists, there may be no missing field to buy. If it is stale, preserve it as history rather than erasing it before a replacement is available.

For unresolved records, rank potential sources by the value of their incremental accepted results. A planning ratio is:

marginal cost per accepted record = added source cost / additional records accepted after prior sources

This ratio must be measured conditionally. A source that resolves many records on an untouched list may add little after another provider has already resolved the easy cases. Segment the analysis by the populations that matter to your business, such as geography or employer type, rather than assuming a universal order.

Provider order also reflects latency, contractual permissions, and data minimization. The cheapest source is not automatically the first source if using it requires sending fields you do not need to disclose. Put hard policy constraints ahead of cost optimization.

Do not assume an aggregator exposes every underlying provider or lets you set the sequence. The consulted FullEnrich API overview establishes aggregation; it does not establish customer control of provider order. If you need that control, request documentation or orchestrate separately contracted sources in your own design. API Overview - FullEnrich API Documentation

Fallback is a state transition

Use explicit internal outcomes rather than a single "failed" flag:

These are editorial internal states, not vendor response values. Map actual API states into them using the current provider schema. A timeout after submitting a request is especially important: it does not prove the provider did nothing. Retrying immediately can create a duplicate paid job.

Fallback should be field-specific. Finding a phone number does not settle a work-email gap. Conversely, a workflow requesting only a work email should not buy personal email and phone information merely because the API supports it.

Verification is evidence with limits

FullEnrich documents separate email statuses and excludes invalid emails from its preferred-email field. Its documentation also makes numerical bounce claims; we do not repeat those as measured outcomes. Email Verification Status - FullEnrich API Documentation

A verification label does not establish that you matched the right person. It also does not establish permission to contact someone, current employment, or inbox placement. Those are separate questions. Store the original status, the time observed, the matched domain, and the rule that accepted or rejected it.

For an uncertain result, design a review path instead of silently downgrading the policy. A reviewer should see why the result was returned, the identity evidence, and the exact unresolved issue. Give them an explicit rejection option; otherwise review queues tend to become approval queues by habit.

Dedupe before spending; make writes idempotent

Use the CRM's stable record ID as the primary internal identity where available. Names are weak identifiers. Email addresses can change, and a person can legitimately have multiple historical addresses. Normalize comparison fields without deleting their original values.

Build an internal idempotency key from the record ID, requested field, policy version, and freshness window. Acquire a durable lock before submitting enrichment. This is a proposed application control, not a claim that a provider accepts an idempotency header. Persist the provider job ID as soon as it is known.

A duplicate callback should be harmless. Store a receipt keyed to the job and result version, check whether the result was already processed, and avoid writing the same proposal again. A callback arriving after suppression or deletion should not recreate the record.

A CRM update needs its own guard. Read the current field version before committing. If a rep has corrected the record since enrichment began, place the proposal in conflict review. "Last response wins" is a poor default for an asynchronous process.

A worked hypothetical cost example

Suppose 1,000 qualified records survive deduplication and suppression. In an invented two-stage design, source A charges $0.02 per attempted lookup and returns 600 accepted work emails. It costs 1,000 × $0.02 = $20. The remaining 400 records proceed to a FullEnrich-style result-billed stage.

Assume that stage produces 280 billable work emails, but your stricter policy accepts only 250. The 280 includes 30 billable results that you hold or reject. Using the displayed FullEnrich rate of $0.055 per credit and the documented one-credit work-email unit, allocated usage cost is 280 × $0.055 = $15.40. The rate is observed; all volumes and source A's price are hypothetical. FullEnrich Pricing: Pay Only for Verified Contacts | Plans from Free Credits and Testing Tips - FullEnrich API Documentation

This is usage allocation, not the amount due on a new subscription. If you buy a hypothetical 1,000-credit allocation at that displayed rate solely for this run, the allocation implies $55 committed to FullEnrich credits. Together with source A, committed data spend would be $75, or $0.08824 per accepted record, with 720 credits unused. The pricing page's rendered total is malformed, so confirm the actual subscription total and currency at checkout; $55 is multiplication, not a verified checkout quote. FullEnrich Pricing: Pay Only for Verified Contacts | Plans from Free

Do not count unused credits as a saving until another legitimate workload uses them. Add orchestration, verification purchased elsewhere, maintenance, and tax separately. If a duplicate submission repeats the 280 billable results, your assumed economics no longer hold. This is why reconciliation belongs in the cost model.

Provenance that survives an audit

For each proposed field, keep the internal record ID, source service, source job ID, requested field, observed timestamp, original vendor status, policy version, accepted/rejected decision, reviewer, and resulting CRM version. These are suggested ledger fields, not an API payload.

Store the minimum raw evidence required to diagnose errors and meet your retention policy. Keeping every full response forever creates another data store to protect and delete. Where the service exposes only its own identity rather than an underlying provider, record that limitation honestly. Do not fabricate provider-level provenance.

The ledger should answer three questions quickly: Why is this value here? What did it cost to obtain? What must happen if the person asks for removal? If answering any one requires searching an employee's personal spreadsheet, the design needs work.

Privacy and suppression are workflow inputs

Use an approved processing purpose, permitted fields, access policy, and retention schedule before enrichment. This is operational guidance, not a jurisdiction-specific legal conclusion. Have the responsible privacy owner decide the applicable requirements; a data vendor's verification label does not decide them.

Check suppression at intake, immediately before a paid request, at callback processing, and before a CRM commit. A record can change status while an asynchronous job is running. Treat suppression as an authoritative state that enrichment cannot overwrite. If you keep a minimal suppression token to prevent reimport, define who may access it and how it is retained.

Design deletion across the staging store, job ledger, exported files, execution logs, and CRM. Mark in-flight jobs as prohibited from writing even where cancellation is unavailable. Keep enough non-content audit information to demonstrate that the instruction was honored without retaining the contact details indefinitely.

Source-grounded integration design

FullEnrich documents asynchronous submission, a returned ID, webhooks, and result retrieval. n8n documents HTTP Request and Webhook nodes. A defensible design is: submit, persist job identity, receive or retrieve results, validate, stage the proposal, approve, then apply a guarded CRM update. This is an untested design, not a claim of a certified end-to-end connector. How Webhooks Work - FullEnrich API Documentation Start Bulk Enrichment - FullEnrich API Documentation Get Enrichment Result - FullEnrich API Documentation HTTP Request Webhook

Respect multiple limits at once. FullEnrich publishes 60 API calls per minute, up to 100 contacts per enrichment bulk, and a default queue of 100 concurrent enrichments. A theoretical contacts-per-minute multiplication is not an achieved throughput promise. Rate Limit - FullEnrich API Documentation

Use a shared limiter for submissions and reconciliation calls. Set a small pilot budget and stop automatically when the ledger's unknown-outcome count grows. If callback authentication is not established, treat a received callback as a signal to retrieve the result through the authenticated API, rather than as authority to change the CRM.

Monitor usefulness and operational health

Track unique eligible inputs, requests submitted, billable results, accepted results, unresolved identities, duplicate events prevented, stale jobs, and CRM conflicts. Calculate both marginal data cost and fully loaded cost per accepted record. Separate source failures from business-policy rejections.

Review accepted results on a representative sample. Compare the source's answer with permitted identity evidence, and record why any accepted record should have been rejected. Change one provider-order or acceptance rule at a time so you can explain its effect. A larger returned count with more identity errors is not an improvement.

Set alerts around action: an operator must know whether to pause intake, replenish an approved budget, repair credentials, or investigate a changed schema. A chart without a named response owner is not a control.

For the implementation sequence, read the FullEnrich and n8n design guide. For orchestration billing, read n8n vs Zapier. Return to the tools hub if you are still deciding which job requires a product.

Sources

Primary pages consulted on November 7, 2026. A link supports the claim next to it. It does not prove a customer uses the product.

• API Overview - FullEnrich API Documentation (S12, checked 2026-11-07)
• Clay Waterfall: maximize your coverage of contact info | Clay.com (S21, checked 2026-11-07)
• Credits and Testing Tips - FullEnrich API Documentation (S30, checked 2026-11-07)
• Email Verification Status - FullEnrich API Documentation (S31, checked 2026-11-07)
• FullEnrich Pricing: Pay Only for Verified Contacts | Plans from Free (S01, checked 2026-11-07)
• How Webhooks Work - FullEnrich API Documentation (S29, checked 2026-11-07)
• Start Bulk Enrichment - FullEnrich API Documentation (S33, checked 2026-11-07)
• Get Enrichment Result - FullEnrich API Documentation (S34, checked 2026-11-07)
• HTTP Request (S24, checked 2026-11-07)
• Webhook (S26, checked 2026-11-07)
• Rate Limit - FullEnrich API Documentation (S32, checked 2026-11-07)