Waterfall Logic

Smart Lead Routing: Prioritize quality over quantity.

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.

API Reference: Waterfall ICP (Keyword) endpoint — full request/response schema and try-it console.

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. Waterfall ICP - BlitzAPI

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.”

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.

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.

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.

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:

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

{
 "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.

Country Codes: Use 2-letter ISO codes as used by LinkedIn (e.g., US, GB, FR). See the Country Codes reference for the full list.

Response Schema

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

{
  "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`.

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+.

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
Search decision-makers across many companies in one call	Find People
Just the company list (no people)	Company Search

Find People

Combine company filters and person filters in a single multi-account search.

Employee Finder

Browse every employee at a single company with paginated results.

Introduction

Getting Started

Core Concepts

Recipes (Use Cases)

Integrations

Appendix

Waterfall Logic

Waterfall Logic

The “Smart Routing” Concept

Real-World Example: The “Marketing First” Strategy

Why this query is powerful

Endpoint

Request Parameters

Top-Level Parameters

Cascade Object Parameters (per tier)

Response Schema

Top-Level Fields

Result Fields (`results[]`)

Person Object (`results[].person`)

Waterfall vs. the Rest of the People Search Family

Find People

Employee Finder

​Waterfall Logic

​The “Smart Routing” Concept

​Real-World Example: The “Marketing First” Strategy

​Why this query is powerful

​Endpoint

​Request Parameters

​Top-Level Parameters

​Cascade Object Parameters (per tier)

​Response Schema

​Top-Level Fields

​Result Fields (results[])

​Person Object (results[].person)

​Waterfall vs. the Rest of the People Search Family

Find People

Employee Finder

Waterfall Logic

The “Smart Routing” Concept

Real-World Example: The “Marketing First” Strategy

Why this query is powerful

Endpoint

Request Parameters

Top-Level Parameters

Cascade Object Parameters (per tier)

Response Schema

Top-Level Fields

Result Fields (`results[]`)

Person Object (`results[].person`)

Waterfall vs. the Rest of the People Search Family