Waterfall enrichment

The job in one paragraph

A waterfall asks several data providers for the same field in a fixed order and stops at the first answer. The first hop matters most, because it sees every row. LeadOcean fits that slot over REST and over a hosted MCP server: one identifier in, the record we hold out, and a 404 with no charge when we hold nothing. LeadOcean does not run the waterfall for you. Your script, a Clay table, a Zapier, Make or n8n flow, or an agent decides what happens on a miss. For the method, read what is waterfall enrichment.

The workflow

1. Check the account. GET /v1/account (MCP: leadocean_get_account). Free. It shows the records you have left.
2. Size the run. POST /v1/people/search?count=true with your filters and "limit": 1, or leadocean_count_leads. Free. meta.total is capped at 100,000.
3. Call hop one. POST /v1/people/enrich (MCP: leadocean_get_lead) with exactly one of email, linkedin_url, phone or person_id. Set reveal_email to true to get the address. 1 record per hit. A 404 costs nothing.
4. Test what came back. Keep a row as filled only if the field you need is present and email_status is verified or catch_all_valid. Anything else goes down the waterfall.
5. Pass the gaps to hop two. Send only the 404s and weak rows to your next provider. LeadOcean charged you nothing for the misses, so hop two sees a smaller list.
6. Add phones last. GET /v2/people/phone (MCP: leadocean_find_phone). 1 record per call. On the v2 endpoint a call that finds nothing still costs 1 record, so run it only on rows that survived your filters.
7. Log the hop. Store which provider filled each field, with the record's fetched_at date. You need it to retire hops that stop paying off.

curl -X POST "https://api.leadocean.io/v1/people/enrich" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"linkedin_url":"https://www.linkedin.com/in/acme-example","reveal_email":true}'

There is no lookup by name plus company name. If a row has a name and a domain, search by domain first, then enrich by person_id. Search costs 1 record per person returned.

A worked example

Take a table of 10,000 prospects, each with a LinkedIn URL. Suppose 7,000 match at hop one (the hit rate is your assumption here, not a result). That is 7,000 records. The 3,000 misses cost nothing and are the only rows your second provider sees.

Now add phones for the 1,500 matched rows that pass your filters, through GET /v2/people/phone. That is 1,500 more records, found or not. Hop one totals 8,500 records.

On Free, the first 1,000 records are yours once, with no card, so you can test the first hop on a slice. On Pro the month is $499, flat, with no per-record price, inside fair use. See pricing.

To size a target list before you spend anything, we ran leadocean_count_leads on 1 October 2026. Filters: jobLevel VP, jobFunction Information Technology, country US, employeeRange 201-500, emailStatus verified. It returned 119 people with a verified email. The count cost 0 records.

Tools that fit

• Enrich Company: the account lookup by domain, with every field listed.
• Enrich Person skill: Claude looks up one person from a LinkedIn URL or email.
• CSV Enricher skill: export a list, let Claude price and enrich it, and keep the rows that missed for the next hop.
• Clay: an HTTP API column calls LeadOcean first and gates paid columns on an empty result.
• Zapier, Make and n8n: branch on a 404 to send the row to your next provider.
• The Exports page in the app at app.leadocean.io: filter builder, column picker and the record price before you start. It has no waterfall builder, so you run the later hops yourself.

For tool comparisons, read the best waterfall enrichment tools. For the term itself, see enrichment.

Pitfalls

• Stale data. The dataset is refreshed monthly, and each record carries its own fetched_at date. A hit can still be a month old, so check that date before you overwrite a field a rep typed.
• Catch-all emails. catch_all and catch_all_valid addresses accept any mail, so a send can still bounce. There is no refund for bounces. Treat a catch-all hit as a gap if your next hop can verify it.
• Rate limits. The limit is 100 requests per second per key, on every plan. A 429 is never metered. Back off and retry, and do not read a 429 as a miss.
• Enum strings. Filter values are exact strings: jobLevel is C-Team, VP or Director, and seniority is lowercase, such as c_suite. Check leadocean_list_enum_values before you build a filter.

FAQ