databar-waterfall

Databar Waterfall Enrichment

Waterfalls try multiple data providers in sequence until one returns a result. This maximizes the chance of finding the data. For example, an "email finder" waterfall might try Provider A first, and if it fails, try Provider B, then C — stopping as soon as one succeeds.

When to use this vs a regular enrichment

• Waterfall: User wants the highest chance of finding the data and doesn't care which provider returns it. Best for email finding, phone lookups, and contact discovery.
• Regular enrichment (databar-enrichment skill): User wants data from a specific provider, or the task only has one relevant provider.

Workflow

1. Identify the user's goal. Common waterfall use cases:

   • Finding someone's email address (given name + company)
   • Looking up a phone number
   • Finding social profiles
   • Any task where the user wants to "try everything"

2. Search for available waterfalls. Call search_waterfalls with a descriptive query (e.g. "email finder", "phone lookup").

3. Pick the best waterfall. Review the results. Check:

   • identifier — the string you'll pass to run it
   • input_params — required parameters
   • available_enrichments count — more providers = higher success rate

4. Determine single vs bulk.

   • If the user provides one record: use run_waterfall
   • If the user provides multiple records: use run_bulk_waterfall

5. Confirm cost with the user. Waterfall pricing varies by provider. Tell the user the waterfall name and that costs depend on which provider succeeds.

   • For bulk: "Running {waterfall_name} on {count} records. Cost depends on which providers succeed."

6. Run the waterfall.

   Single record:

   run_waterfall({
     waterfall_identifier: "email_getter",
     params: { full_name: "John Smith", company_name: "Google" }
   })
   

   Multiple records:

   run_bulk_waterfall({
     waterfall_identifier: "email_getter",
     params_list: [
       { full_name: "John Smith", company_name: "Google" },
       { full_name: "Jane Doe", company_name: "Microsoft" }
     ]
   })