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

# Waterfall Logic

# Waterfall Logic

> Smart Lead Routing: Prioritize quality over quantity.

<div style={{position:'absolute',width:'1px',height:'1px',padding:0,margin:'-1px',overflow:'hidden',clipPath:'inset(50%)',whiteSpace:'nowrap',border:0}}>
  > **Agents & LLMs**: a Markdown version of this page is available by appending `.md` to the URL, and the full documentation index is at [llms.txt](https://docs.blitz-api.ai/llms.txt).
</div>

<Info>**API Reference**: [`Waterfall ICP (Keyword)` endpoint](/api-reference/people-search/waterfall-icp-search) — full request/response schema and try-it console.</Info>

In modern B2B growth, **more leads is not the goal. Better leads are.**

The **Waterfall ICP** engine (`POST /v2/search/waterfall-icp-keyword`) is designed to solve one specific problem: **Finding the single best decision-maker** at a target company without manual sorting.

<img src="https://mintcdn.com/blitzapi-6cafe00d/lMjF8LYneijS3EL2/images/waterfall-icp-blitz.png?fit=max&auto=format&n=lMjF8LYneijS3EL2&q=85&s=541abd6aa4272873e38e970697052905" alt="Waterfall ICP - BlitzAPI" style={{ width:"48%" }} width="1024" height="1024" data-path="images/waterfall-icp-blitz.png" />

## The "Smart Routing" Concept

Most APIs return a list of 50 employees and leave you to filter them. BlitzAPI works differently. You define a **Hierarchy of Preference** (a Cascade), and our engine executes a sequential search logic.

It attempts to find your "Dream Contact." If, and only if, that fails, it moves to your "Plan B."

<Steps>
  <Step title="Priority 1: The Decision Maker">
    **"I want the CMO."**

    The API scans the company. If a CMO is found, the search **stops immediately**. You get the top-ranked result.
  </Step>

  <Step title="Priority 2: The Deputy">
    **"If no CMO, give me the Marketing Manager."**

    If Priority 1 yielded no results, the engine automatically triggers the second level of your cascade.
  </Step>

  <Step title="Priority 3: The Fallback">
    **"If no Marketing team, give me the CEO."**

    As a last resort, the engine looks for the founder to ensure you don't leave the account empty-handed.
  </Step>
</Steps>

***

## Real-World Example: The "Marketing First" Strategy

Let's look at a complex query. Here, we want to target **Welcome to the Jungle**, but we have a very specific preference order.

**The Strategy:**

1. **Tier 1**: Get the **Marketing Director/CMO** (Global).
2. **Tier 2**: If missing, get a **Growth Manager** (Global).
3. **Tier 3**: If missing, get a **Brand/Comms Director** (Global).
4. **Tier 4**: If missing, try a broader keyword search in **North America only**.
5. **Tier 5**: If all else fails, get the **CEO**.

```json theme={null} theme={null}
{
 "company_linkedin_url": "https://www.linkedin.com/company/wttj-fr",
 "cascade": [
   {
     "include_title": ["Marketing Director", "Head Marketing", "Chief Marketing Officer"],
     "exclude_title": ["assistant", "intern", "product", "junior"],
     "location": ["WORLD"],
     "include_headline_search": false
   },
   {
     "include_title": ["Marketing Manager", "Head Growth", "Growth manager"],
     "exclude_title": ["junior", "assistant", "intern", "hacker"],
     "location": ["WORLD"],
     "include_headline_search": false
   },
   {
     "include_title": ["Communication Director", "Brand Director", "Content Director"],
     "exclude_title": ["junior", "assistant", "intern", "UX", "UI", "Design"],
     "location": ["WORLD"],
     "include_headline_search": false
   },
   {
     "include_title": ["Communication", "marketing", "growth", "brand"],
     "exclude_title": ["junior", "assistant", "intern", "product"],
     "location": ["US", "CA"],
     "include_headline_search": true
   },
   {
     "include_title": ["CEO", "founder", "cofounder", "owner", "General Director"],
     "exclude_title": ["junior", "assistant", "intern"],
     "location": ["WORLD"],
     "include_headline_search": false
   }
 ],
 "max_results": 10
}
```

### Why this query is powerful

* **Precision**: By using `exclude_title`, we focus the results on senior profiles and avoid matching interns or assistants who aren't decision-makers.
* **Flexibility**: In step 4, we switch `include_headline_search` to `true`. This allows us to catch people who write "Helping companies grow" in their bio, even if their job title isn't exactly "Growth Manager".
* **Safety Net**: The final step ensures that if the Marketing team is invisible, we still capture the CEO to start a top-down conversation.

***

## Endpoint

**`POST /v2/search/waterfall-icp-keyword`**

Queries BlitzAPI's proprietary dataset to deliver results instantly.

* **Paid plans**: Unlimited (included in Unlimited Leads+)
* **Latency**: \< 600ms

***

## Request Parameters

### Top-Level Parameters

| Parameter              | Type      | Required | Description                                                                                                    |
| :--------------------- | :-------- | :------- | :------------------------------------------------------------------------------------------------------------- |
| `company_linkedin_url` | `string`  | Yes      | The full LinkedIn URL of the target company (e.g., `"https://www.linkedin.com/company/openai"`).               |
| `cascade`              | `array`   | Yes      | Ordered array of search tiers (**up to 8 levels**). The engine tries each tier until `max_results` is reached. |
| `max_results`          | `integer` | No       | Maximum number of people to return across all tiers. Default: `1`. Max: `25`.                                  |

### Cascade Object Parameters (per tier)

| Parameter                 | Type      | Required | Description                                                                                            |
| :------------------------ | :-------- | :------- | :----------------------------------------------------------------------------------------------------- |
| `include_title`           | `array`   | Yes      | Job titles to match (e.g., `["CEO", "CTO"]`). Partial matching — `"VP Sales"` matches `"VP of Sales"`. |
| `exclude_title`           | `array`   | No       | Titles to exclude. Use to filter out `["Assistant", "Intern", "Junior"]`.                              |
| `location`                | `array`   | No       | LinkedIn Country Codes (e.g., `["US", "FR"]`). Use `["WORLD"]` for global. Default: `["WORLD"]`.       |
| `include_headline_search` | `boolean` | No       | If `true`, keywords match against the user's LinkedIn bio/headline, not just their formal job title.   |

<Info>
  **Country Codes**: Use 2-letter ISO codes as used by LinkedIn (e.g., `US`, `GB`, `FR`). See the [Country Codes reference](/guide/reference/appendix#country-codes-linkedin) for the full list.
</Info>

***

## Response Schema

A successful request returns a JSON object with the following structure:

```json theme={null} theme={null}
{
  "results_length": 3,
  "results": [
    {
      "icp": 1,
      "ranking": 1,
      "what_matched": [{ "key": "include_title", "value": "VP Sales" }],
      "person": {
        "first_name": "Jane",
        "last_name": "Doe",
        "full_name": "Jane Doe",
        "headline": "VP of Sales at Acme Corp",
        "about_me": "Scaling B2B revenue teams...",
        "location": {
          "city": "New York",
          "state_code": "NY",
          "country_code": "US",
          "continent": "North America"
        },
        "linkedin_url": "https://www.linkedin.com/in/janedoe",
        "connections_count": 2500,
        "profile_picture_url": "https://media.licdn.com/...",
        "experiences": [
          {
            "job_title": "VP of Sales",
            "company_linkedin_url": "https://www.linkedin.com/company/acme",
            "job_start_date": "2023-03-01",
            "job_end_date": null,
            "job_is_current": true
          }
        ],
        "education": [],
        "skills": ["B2B Sales", "SaaS", "Revenue Operations"],
        "certifications": []
      }
    },
    {
      "icp": 2,
      "ranking": 2,
      "what_matched": [{ "key": "include_title", "value": "Sales Director" }],
      "person": {
        "first_name": "Alice",
        "last_name": "Martin",
        "full_name": "Alice Martin",
        "headline": "Sales Director at Acme Corp",
        "linkedin_url": "https://www.linkedin.com/in/alicemartin",
        "location": { "city": "London", "country_code": "GB", "continent": "Europe" }
      }
    }
  ]
}
```

### Top-Level Fields

| Field            | Type      | Description                                                          |
| :--------------- | :-------- | :------------------------------------------------------------------- |
| `results_length` | `integer` | Total number of results returned. `0` if no match found.             |
| `results`        | `array`   | Array of matched people, ordered by cascade priority then relevance. |

### Result Fields (`results[]`)

| Field          | Type      | Description                                                                                        |
| :------------- | :-------- | :------------------------------------------------------------------------------------------------- |
| `icp`          | `integer` | Cascade **tier** that matched this person. `1` = highest priority (Tier 1), `2` = Tier 2, etc.     |
| `ranking`      | `integer` | **Overall relevance rank** within the company (1 = most relevant). Use to adapt outreach strategy. |
| `what_matched` | `array`   | Which filter criteria matched. Each entry has `key` (e.g., `"include_title"`) and `value`.         |
| `person`       | `object`  | Full person profile. Pass `person.linkedin_url` to enrichment endpoints for email/phone.           |

### Person Object (`results[].person`)

| Field                 | Type             | Description                                                                                                                        |
| :-------------------- | :--------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| `first_name`          | `string \| null` | First name.                                                                                                                        |
| `last_name`           | `string \| null` | Last name.                                                                                                                         |
| `full_name`           | `string \| null` | Full display name.                                                                                                                 |
| `headline`            | `string \| null` | LinkedIn headline.                                                                                                                 |
| `about_me`            | `string \| null` | LinkedIn "About" section.                                                                                                          |
| `location`            | `object`         | Location with `city`, `state_code`, `country_code`, `continent`.                                                                   |
| `linkedin_url`        | `string`         | Person LinkedIn URL — **use this** as input for `/v2/enrichment/email` and `/v2/enrichment/phone`.                                 |
| `connections_count`   | `number \| null` | LinkedIn connections count.                                                                                                        |
| `profile_picture_url` | `string \| null` | URL to profile picture.                                                                                                            |
| `experiences`         | `array`          | Work history. Each entry: `job_title`, `company_linkedin_url`, `job_start_date`, `job_end_date`, `job_is_current`, `job_location`. |
| `education`           | `array`          | Education history. Each entry: `degree`, `organization`, `start_date`, `end_date`.                                                 |
| `skills`              | `array`          | List of skills (strings).                                                                                                          |
| `certifications`      | `array`          | List of certifications. Each entry: `name`, `authority`, `url`.                                                                    |

<Note>
  **`icp` vs `ranking` — how to use both:**

  * `icp` tells you *which tier* matched: route ICP 1–2 to your AE team, ICP 3–5 to SDR.
  * `ranking` tells you *position within the company*: apply multichannel (email+LinkedIn+call) to ranking 1–3, calling-only to 4–10, and nurturing sequences to 11+.
</Note>

***

## Waterfall vs. the Rest of the People Search Family

Waterfall ICP is account-scoped and returns **one best contact**. If your need is different, pick the right tool:

| Use Case                                                     | Best Endpoint                                      |
| :----------------------------------------------------------- | :------------------------------------------------- |
| Single best decision-maker at a **known** company            | **Waterfall ICP** (this page)                      |
| Map *all* employees at one specific company                  | [Employee Finder](/guide/concepts/employee-finder) |
| Search decision-makers across **many companies** in one call | [Find People](/guide/concepts/find-people)         |
| Just the company list (no people)                            | [Company Search](/guide/concepts/company-search)   |

<CardGroup cols={2}>
  <Card title="Find People" icon="users-viewfinder" href="/guide/concepts/find-people">
    Combine company filters and person filters in a single multi-account search.
  </Card>

  <Card title="Employee Finder" icon="users" href="/guide/concepts/employee-finder">
    Browse every employee at a single company with paginated results.
  </Card>
</CardGroup>