| The Bottom Line |
The problem | Running waterfall enrichment in Claude Code manually means managing 10+ API keys, writing custom fallback logic for each provider, and handling rate limits, auth formats, and error codes that differ across every single one |
The fix | The Databar API wraps 100+ data providers behind one API key and one consistent response format, accessible through standard REST endpoints |
Code difference | ~120 lines of fragile multi-API code vs ~15 lines with Databar |
Cost difference | 10 separate subscriptions ($500 to $2,000+/mo combined) vs one Databar plan starting at $129/mo |
Best for | GTM engineers and technical founders who run enrichment workflows directly inside Claude Code |
Bad data costs companies roughly $15 million per year on average, according to research aggregated across multiple industry studies. The fix is not more data. It is better data from more sources, checked in sequence, with automatic fallback when one provider comes up empty.
That is what waterfall enrichment does. You query Provider A. If it returns nothing, you query Provider B. Then C. Then D. Until the record is complete or you have exhausted your sources. The concept is simple. The implementation, when you try to do it yourself inside Claude Code, is a mess.
This tutorial shows both sides. First, the manual approach with 10 separate APIs. Then, the same workflow using the Databar API. The difference is not subtle.
1. What Waterfall Enrichment Means
Waterfall enrichment is a sequential data lookup pattern. You have a contact record with missing fields. Instead of querying one data provider and accepting whatever it returns (or does not return), you cascade through multiple providers in priority order until every field is filled.
Take email enrichment as an example. You have a first name, last name, and company domain. You need a verified business email.
→ Provider 1 (fastest, cheapest): returns nothing
→ Provider 2 (mid-tier): returns an email, but it is unverified
→ Provider 3 (premium): returns a verified email
→ Verification step: confirms the email is deliverable before writing it to your CRM
Without the waterfall, you get one shot. If Provider 1 misses, the record stays empty. With the waterfall, your fill rate jumps dramatically because each subsequent provider covers gaps the previous one left.
The same pattern applies to phone numbers, LinkedIn URLs, firmographic data, technographic data, and any other field you need for outbound. The more providers in your waterfall, the higher your fill rate. But the more providers you manage manually, the more complex your code becomes.
2. The Manual Approach: 10 API Keys, 10 Problems
Here is what waterfall enrichment looks like when you wire it up yourself inside Claude Code. For this example, we are finding a verified email from a name and company domain, using three providers plus a verification step.
import requests
import time
# Provider 1: Hunter
def try_hunter(first_name, last_name, domain):
try:
resp = requests.get(
"https://api.hunter.io/v2/email-finder",
params={
"domain": domain,
"first_name": first_name,
"last_name": last_name,
"api_key": "HUNTER_API_KEY_HERE"
},
timeout=10
)
data = resp.json()
if data.get("data", {}).get("email"):
return data["data"]["email"]
except (requests.Timeout, requests.ConnectionError, KeyError):
pass
return None
# Provider 2: Apollo
def try_apollo(first_name, last_name, domain):
try:
resp = requests.post(
"https://api.apollo.io/api/v1/people/match",
json={
"first_name": first_name,
"last_name": last_name,
"organization_name": domain,
"reveal_personal_emails": False
},
headers={"x-api-key": "APOLLO_API_KEY_HERE"},
timeout=10
)
data = resp.json()
if data.get("person", {}).get("email"):
return data["person"]["email"]
except (requests.Timeout, requests.ConnectionError, KeyError):
pass
return None
# Provider 3: People Data Labs
def try_pdl(first_name, last_name, domain):
try:
resp = requests.get(
"https://api.peopledatalabs.com/v5/person/enrich",
params={
"first_name": first_name,
"last_name": last_name,
"company": domain
},
headers={"X-Api-Key": "PDL_API_KEY_HERE"},
timeout=10
)
data = resp.json()
if data.get("work_email"):
return data["work_email"]
except (requests.Timeout, requests.ConnectionError, KeyError):
pass
return None
# Verification: Emailable
def verify_email(email):
try:
resp = requests.get(
"https://api.emailable.com/v1/verify",
params={
"email": email,
"api_key": "EMAILABLE_API_KEY_HERE"
},
timeout=15
)
data = resp.json()
return data.get("state") == "deliverable"
except:
return False
# The waterfall
def find_email(first_name, last_name, domain):
providers = [try_hunter, try_apollo, try_pdl]
for provider in providers:
email = provider(first_name, last_name, domain)
if email:
if verify_email(email):
return {"email": email, "verified": True}
else:
continue # try next provider
time.sleep(0.5) # rate limit buffer
return {"email": None, "verified": False}
That is roughly 80 lines of code for a three-provider email waterfall with verification. And this is the simplified version. A production implementation needs to handle:
Rate limiting per provider. Hunter allows 500 requests per month on the free tier. Apollo has different limits depending on your plan. People Data Labs throttles by requests per minute. Each provider uses a different rate limiting scheme, and exceeding it silently degrades your results.
Auth format differences. Hunter uses a query parameter. Apollo uses a custom header. PDL uses a different custom header. Every provider authenticates differently.
Response format parsing. The email field lives in a different location in every provider's JSON response. data.data.email vs person.email vs work_email. One typo in your parsing logic and you silently skip valid results.
Error handling edge cases. What happens when a provider returns a 429 (rate limited)? What about a 503 (temporarily down)? Do you retry? Skip? Queue for later? Each provider has different retry guidance.
Key management. Ten providers means ten API keys to create, store, rotate, and pay for. In Claude Code, those keys either live in environment variables (manageable) or get hardcoded into scripts (a security problem).
Multiply this by every data type you need: emails, phone numbers, LinkedIn URLs, company firmographics, technographics, hiring signals. A full enrichment waterfall across five data types with three providers each is 15+ API integrations. That is 15 sets of auth logic, 15 response parsers, 15 rate limiters, and 15 billing relationships.
Nobody wants to maintain that. Nobody should have to.
3. The Clean Way: One API, One Key
The Databar API wraps all of those providers behind a single REST interface. Here is the same email waterfall:
import requests
DATABAR_API_KEY = "YOUR_DATABAR_API_KEY"
BASE_URL = "https://api.databar.ai/v1"
# Run the email finder waterfall
response = requests.post(
f"{BASE_URL}/waterfalls/run",
headers={"x-apikey": DATABAR_API_KEY},
json={
"waterfall": "email_getter",
"params": {
"first_name": "Patrick",
"last_name": "Collison",
"company": "stripe.com"
}
}
)
result = response.json()
print(result["email"]) # verified email
That is it. One POST request replaces 80+ lines of multi-provider code. One API key replaces four. One consistent response format replaces four different JSON structures you have to parse individually.
What is happening behind the scenes: Databar's email_getter waterfall queries its network of data providers in optimized sequence, cascading through them until a verified result is found. When the waterfall supports it (indicated by the is_email_verifying flag in the waterfalls list endpoint), email verification runs automatically as part of the cascade. You do not write the fallback logic. You do not manage the rate limits. You do not parse different response formats.
For bulk processing, the API has a dedicated batch endpoint:
# Bulk waterfall enrichment
leads = [
{"first_name": "Patrick", "last_name": "Collison", "company": "stripe.com"},
{"first_name": "Dylan", "last_name": "Field", "company": "figma.com"},
{"first_name": "Vlad", "last_name": "Tenev", "company": "robinhood.com"},
# ... hundreds more
]
response = requests.post(
f"{BASE_URL}/waterfalls/bulk-run",
headers={"x-apikey": DATABAR_API_KEY},
json={
"waterfall": "email_getter",
"items": leads
}
)
task = response.json()
# For bulk operations, poll the task status endpoint
# GET /v1/tasks/{task_id} until results are ready
The bulk endpoint handles parallel processing, retry logic, and result aggregation. For async bulk jobs, you poll the /v1/tasks/{task_id} endpoint until results are ready. In Claude Code, you can process a CSV of 500 leads with two API calls (one to start, one to retrieve) instead of writing a loop with sleep timers and error catching.
4. Available Waterfalls
The Databar API exposes its waterfall catalog through the GET /v1/waterfalls/ endpoint. Hit it with your API key and you get back every pre-configured cascade available:
response = requests.get(
f"{BASE_URL}/waterfalls/",
headers={"x-apikey": DATABAR_API_KEY}
)
waterfalls = response.json()
for w in waterfalls:
print(f"{w['identifier']}: {w['name']}")
print(f" Inputs: {[p['name'] for p in w['input_params']]}")
print(f" Outputs: {[f['name'] for f in w['output_fields']]}")
print(f" Providers: {len(w['available_enrichments'])}")
Each waterfall object in the response tells you exactly what it needs and what it returns:
Email finder waterfall (email_getter): Takes first_name, last_name, and company. Returns a verified business email. The is_email_verifying flag is true, meaning automatic verification through services like Emailable is built into the cascade. The available_enrichments array lists each provider in the sequence with its per-request price, so you know exactly what each lookup costs before you run it.
Person finder waterfall (person_getter): Takes an email. Returns first_name, last_name, and linkedin_url. Useful for enriching inbound leads where you only have an email address.
Phone number waterfall: Takes contact identifiers. Returns direct dial or mobile number. Cascades through phone data specialists.
Company enrichment waterfall: Takes a domain. Returns firmographic data including employee count, revenue range, industry, tech stack, and funding history.
The available_enrichments field on each waterfall lists the specific data providers that will be queried in order, along with pricing per request. The waterfall enrichment engine runs through these providers in optimized order: cheapest and fastest first, premium sources only when earlier providers miss.
5. Building a Claude Code Skill Around the Databar API
The real power shows up when you combine the API with a Claude Code skill. Instead of running one-off scripts, you teach Claude Code a repeatable enrichment workflow.
Here is a skill that turns any CSV of prospects into fully enriched, outreach-ready records:
---
name: waterfall-enrichment
description: Enrich a CSV of prospects using Databar waterfall enrichment API. Use when the user provides a lead list and needs emails, phone numbers, or company data.
---
# Waterfall Enrichment Skill
## Overview
Process a CSV of prospects through Databar waterfall enrichment to fill missing emails, phone numbers, LinkedIn URLs, and company data. Uses the Databar REST API at /v1/waterfalls/run and /v1/waterfalls/bulk-run.
## Setup
- API key is stored in the environment variable DATABAR_API_KEY
- Base URL: https://api.databar.ai/v1
- Auth: x-apikey header
## Steps
1. Read the input CSV and identify columns for: first name, last name, company/domain
2. For records missing email: POST to /v1/waterfalls/bulk-run with waterfall "email_getter"
3. For records missing phone: POST to /v1/waterfalls/bulk-run with the phone waterfall
4. For records missing company data: POST to /v1/waterfalls/bulk-run with the company waterfall
5. For bulk jobs, poll GET /v1/tasks/{task_id} until results are ready
6. Merge enriched data back into the original CSV
7. Flag records where critical fields are still missing after enrichment
8. Output the enriched CSV with a summary of fill rates per field
## Quality Rules
- Only write verified emails to the output (check is_email_verifying on the waterfall)
- Mark unverified results as "Unverified" rather than dropping them
- Include a "sources" column showing which provider returned each data point
- Report total credits consumed at the end of the run
With this skill installed, you tell Claude Code "enrich this lead list" and it knows exactly what to do. It reads your CSV, calls the correct waterfall endpoints, handles the async task polling for bulk jobs, and gives you back a clean, enriched file. No API key juggling. No fallback logic. No parsing gymnastics.
6. Side-by-Side: What You Are Actually Comparing
| Manual (10 APIs) | Databar API |
Setup time | 2 to 4 hours per provider (auth, parsing, error handling) | 5 minutes (get API key, make first request) |
Lines of code | ~80 per data type, per waterfall | ~15 per data type, per waterfall |
API keys to manage | 10+ (one per provider) | 1 |
Rate limit handling | Custom per provider | Handled by Databar |
Response parsing | Different JSON structure per provider | Consistent format across all providers |
Email verification | Separate API call and integration | Built into the waterfall |
Bulk processing | Custom batching, retry, and sleep logic | Single bulk endpoint with async task polling |
Provider coverage | Limited to the APIs you integrated | 100+ providers behind one endpoint |
Monthly cost | $500 to $2,000+ across subscriptions | Starting at $129/mo |
Maintenance | Every provider API change breaks your code | Databar handles provider updates |
7. When to Use Each Approach
The manual approach makes sense in exactly one scenario: you are building a product where enrichment is a core differentiator and you need granular control over every provider interaction, retry policy, and caching layer. If you are building a Clay competitor, by all means manage your own provider integrations.
For everyone else, meaning GTM teams, agencies, RevOps, sales engineers, founders running outbound, the unified API approach wins on every dimension. The time you save on integration and maintenance goes directly into campaign strategy, messaging, and the work that actually produces pipeline.
Within Claude Code specifically, the Databar API has an additional advantage: context efficiency. Claude Code has a finite context window. A 120-line multi-provider script eats into that window. A 15-line API call leaves room for Claude to think about data quality, segmentation, and personalization instead of plumbing.
8. Getting Started in Claude Code
Step 1: Get your Databar API key from your workspace under Integrations. Set it as an environment variable:
export DATABAR_API_KEY="your_key_here"
Step 2: Explore available waterfalls. Ask Claude Code to list what is available:
"Call GET https://api.databar.ai/v1/waterfalls/ with my Databar API key and show me the available waterfalls, their inputs, and their per-provider pricing."
Claude Code will make the request, parse the response, and show you every waterfall identifier, its required input parameters, output fields, and the cost per enrichment provider in the sequence.
Step 3: Run your first waterfall enrichment. Ask Claude Code to enrich a single contact:
"Find the verified business email for Sarah Chen at Figma using the Databar email_getter waterfall. POST to /v1/waterfalls/run."
Claude Code will call the endpoint, return the verified email, and show you the source provider and credits consumed.
Step 4: Scale to bulk. Drop a CSV of 50 prospects into your project folder and ask Claude Code to run the enrichment skill. It will POST to /v1/waterfalls/bulk-run, poll the task status endpoint until results are ready, and merge everything back into your CSV. Review the output for fill rates and data quality before scaling to larger lists.
For production-scale enrichment across thousands of records, the Databar API supports bulk operations that process records in parallel without hitting Claude Code's sequential processing limitation.
9. The Enrichment Stack That Actually Works
The most effective pattern for running enrichment inside Claude Code is not pure API calls and not pure manual scripting. It is a layered approach:
→ Claude Code handles the logic. Reading CSVs, deciding which records need enrichment, defining quality thresholds, and analyzing results.
→ The Databar API handles the data. Running waterfalls, managing provider cascades, verifying results, and returning clean data.
→ Your CRM handles the storage. HubSpot, Salesforce, or whatever system of record your team uses receives the enriched output through Databar's native integrations or a CSV import.
That three-layer stack gives you the flexibility of Claude Code's reasoning (segmentation, scoring, personalization) with the scale and reliability of a dedicated enrichment platform. Neither one replaces the other. Together, they cover the full pipeline from raw lead list to outreach-ready, CRM-synced prospect database.
FAQ
Can I use the Databar API directly in Claude Code?
Yes. The Databar API is a standard REST API that works inside any Claude Code session through Python's requestslibrary (or any HTTP client). You set your API key as an environment variable and call waterfall endpoints directly from Python scripts or through a Claude Code skill. The API handles all provider communication, rate limiting, and response parsing behind a single consistent interface.
How many providers does the Databar waterfall query?
The Databar platform connects to 100+ data providers. Each waterfall type (email, phone, company, person) cascades through the relevant subset of providers in an optimized order. You can configure which providers to include and their priority through the API. The system queries providers sequentially, stopping when verified data is found, so you only pay for the providers that were actually needed.
Is the Databar API free to use?
The API itself has no separate licensing cost. You need a Databar account to use it, and enrichment requests consume credits based on your plan. Plans start at $129/mo, and you only pay for successful requests that return data. Failed lookups and empty results do not count against your credits.
What happens when all providers in the waterfall return nothing?
The waterfall returns a structured response indicating that no data was found, along with metadata showing which providers were queried. Your skill or script can then flag those records for manual research or alternative approaches. Empty results do not consume credits on Databar, so failed lookups cost nothing.
Recent articles
See all
