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

# Waterfalls

> Build enrichment chains that try providers in order and accept the first result, used by the enrich node in workflows.

A **waterfall** is an ordered list of enrichment providers that Default works through one by one.
When the **enrich** node in a workflow runs, it calls the first provider; if that provider
returns a result, the chain stops and uses it. If it doesn't, Default tries the next provider,
and so on, until one succeeds or the list is exhausted. This approach maximizes hit rate while
keeping enrichment costs predictable.

<Note>
  Open **Settings** from the **Dock** (the app bar at the bottom of the screen), then select
  **Data Model** under **Workspace Settings**, then **Waterfalls**. Admin access is required.
</Note>

## Waterfalls list

The Waterfalls page opens with a **Primary Waterfall** banner and a card grid of all your
waterfalls.

<Frame>
  <img src="https://mintcdn.com/default-b6d0c477/BpR0uaqGAtN7_xb-/images/settings/waterfalls.png?fit=max&auto=format&n=BpR0uaqGAtN7_xb-&q=85&s=6f11b5131e40bd17035ea4ea6830c422" alt="The Waterfalls page" width="608" height="780" data-path="images/settings/waterfalls.png" />
</Frame>

### Primary waterfall

The **Primary Waterfall** banner at the top of the page lets you designate one waterfall as the
workspace default. The primary waterfall is used for enrichment requests made by workflows when
no specific waterfall is referenced. Select a waterfall from the **Primary Waterfall** dropdown
to set it.

Each card in the grid shows the waterfall's provider icons, name, and the maximum number of
enrichment credits it can consume per call (the sum of all providers' per-call costs, in a
worst-case scenario where every provider is tried).

A **Primary** badge marks the current primary waterfall.

### Search

Use the **Search Waterfalls** bar to filter cards by name or description.

## Create a waterfall

Select **New Waterfall** to open the creation dialog.

<Steps>
  <Step title="Name and describe the waterfall">
    Enter a **Name** for the waterfall (for example, `Email Finder`). Add an optional
    **Description** to explain its purpose, such as
    `Tries Apollo then Clearbit to find a verified work email`.
  </Step>

  <Step title="Add and order providers">
    Under **Enrichment order**, select **Add Provider** to open the provider picker. You can
    add up to **5 providers** per waterfall. The available enrichment providers are:

    | Provider             | What it provides                          |
    | -------------------- | ----------------------------------------- |
    | **Clearbit**         | Person and company data enrichment.       |
    | **Apollo**           | B2B contact information and company data. |
    | **People Data Labs** | Person data and social profiles.          |

    Each provider row shows its position number and the credit cost per call. Drag the handle
    on any row to change the order. The provider at position 1 is tried first.

    To remove a provider, hover the row and select the trash icon.
  </Step>

  <Step title="Verify provider fields (optional)">
    Once you have at least one provider selected, an alert appears offering to **View** the
    enrichment fields that the current provider set can return. Select **View** to open the
    provider fields panel and confirm the waterfall covers the fields you need before saving.

    Select **Back** to return to the form.
  </Step>

  <Step title="Save">
    Select **Create Waterfall**. The new waterfall appears in the card grid.
  </Step>
</Steps>

## Edit a waterfall

Hover a waterfall card and select the pencil icon, or open the card's context menu and choose
**Edit**. The edit dialog is identical to the creation dialog. Update the name, description,
or provider list and select **Save changes**.

## Set a waterfall as primary

To change which waterfall is primary, either:

* Use the **Primary Waterfall** dropdown in the banner at the top of the page, or
* Open a waterfall card's context menu and select **Make Primary**.

## Delete a waterfall

Open a waterfall card's context menu and select **Delete**. A confirmation dialog appears with
the waterfall's name. Confirm to permanently remove it. Deletion cannot be undone.

<Note>
  Before deleting a waterfall, check whether any workflow **enrich** nodes reference it. Those
  nodes will stop resolving a waterfall after deletion.
</Note>

## Use a waterfall in a workflow

Reference a waterfall from the **enrich** node in any workflow. In the enrich node configuration,
select the waterfall you want to use. If no waterfall is specified, the node uses the workspace's
**primary waterfall** automatically.