> ## Documentation Index
> Fetch the complete documentation index at: https://docs.databar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Waterfall email finder

> Find verified emails by trying multiple data providers in sequence with automatic fallback.

A waterfall tries multiple data providers one after another until one returns a result. This is the best way to maximize email coverage without writing fallback logic yourself.

## What you will do

1. Search for a waterfall that finds emails
2. Run it for a single contact
3. Run it in bulk for a list

## Prerequisites

* A Databar API key ([get one here](https://databar.ai))
* A name and company (or domain) for the person you want to find

## Step 1: Find a waterfall

Search available waterfalls:

```bash theme={null}
curl "https://api.databar.ai/v1/waterfalls/?q=email" \
  -H "x-apikey: YOUR_API_KEY"
```

Each waterfall lists the providers it uses and the input parameters it expects. Pick the one that matches your data.

## Step 2: Run for a single contact

```bash theme={null}
curl -X POST "https://api.databar.ai/v1/waterfalls/WATERFALL_ID/run" \
  -H "x-apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "full_name": "John Smith",
      "company": "Google"
    }
  }'
```

You will receive a `task_id`. Poll it to get results:

```bash theme={null}
curl "https://api.databar.ai/v1/tasks/YOUR_TASK_ID" \
  -H "x-apikey: YOUR_API_KEY"
```

The response includes which provider returned the result and whether the email was verified.

## Step 3: Run in bulk

For multiple contacts, use the bulk endpoint:

```bash theme={null}
curl -X POST "https://api.databar.ai/v1/waterfalls/WATERFALL_ID/bulk-run" \
  -H "x-apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": [
      {"full_name": "Sarah Chen", "company": "Stripe"},
      {"full_name": "James Lee", "company": "Notion"}
    ]
  }'
```

<Warning>
  Task data is stored for **24 hours**. Make sure to retrieve and save your results before they expire.
</Warning>

## With the Python SDK

```python theme={null}
from databar import DatabarClient

client = DatabarClient()

result = client.run_waterfall_sync(WATERFALL_ID, {
    "full_name": "John Smith",
    "company": "Google"
})
print(result)

# Bulk
results = client.run_waterfall_bulk_sync(WATERFALL_ID, [
    {"full_name": "Sarah Chen", "company": "Stripe"},
    {"full_name": "James Lee", "company": "Notion"},
])
for r in results:
    print(r)
```

## Next steps

<CardGroup cols={2}>
  <Card title="Enrich leads" icon="magnifying-glass" href="/guides/enrich-leads">
    Enrich a batch of leads with company and contact data.
  </Card>

  <Card title="Table enrichment pipeline" icon="table" href="/guides/table-enrichment-pipeline">
    Store data in a table and run enrichments across all rows.
  </Card>
</CardGroup>