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 best decision-makers at a target company, in your order of preference, 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 first looks for your “Dream Contact.” Every person it finds takes one of the max_results slots. If the slots are not full, it moves to your “Plan B” and fills the slots that are left, and so on down the cascade.

Priority 1: The Decision Maker

“I want the CMO.”The API scans the company for tier 1 matches. Each match takes a slot, and tier 1 people always come first in the results. If tier 1 alone fills max_results, the search stops here.

Priority 2: The Deputy

“Then, if there are slots left, add the Marketing Manager.”If tier 1 found fewer people than max_results, the engine runs the second level of your cascade and fills the remaining slots. Someone already found in an earlier tier is not returned twice.

Priority 3: The Fallback

“And if there are still slots left, add the CEO.”The same rule applies to every tier that follows. The search ends when max_results is full or when there are no tiers left, so the founder can still make sure you don’t leave the account empty-handed.

Example: with max_results: 5, if tier 1 finds 1 person, you get that person plus up to 4 people from tier 2 and the tiers after it. If you only want the single best match, set max_results: 1.

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 there are slots left, add a Growth Manager (Global).
Tier 3: If there are still slots left, add a Brand/Comms Director (Global).
Tier 4: Then try a broader keyword search in North America only.
Tier 5: Finally, add 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 whose LinkedIn headline says “Growth advisor for B2B SaaS”, even if their job title is just “Consultant”. Keywords match whole words, so the same headline written as “Helping companies grow” would not match growth.
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
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 (1 to 10 tiers). The engine fills `max_results` starting from the first tier, and moves to the next tier while slots are left.
`max_results`	`integer`	No	Maximum number of people to return across all tiers. Default: `10`. Max: `100`.
`profile_min_connections`	`number`	No	Minimum number of LinkedIn connections a profile must have to be returned. Default: `0`.

Cascade Object Parameters (per tier)

Parameter	Type	Required	Description
`include_title`	`array`	Yes	Job title phrases to match (e.g., `["CEO", "CTO"]`). 1 to 50 phrases. Keyword matching: all words of a phrase must be in the title, in any order, as whole words. `"VP Sales"` matches `"VP of Sales"` and `"Sales VP"`. See Keyword Filters.
`exclude_title`	`array`	No	Title phrases to exclude, with the same matching rules. Use to filter out `["Assistant", "Intern", "Junior"]`. Up to 50 phrases. Also checked against the headline when `include_headline_search` is `true`.
`location`	`array`	No	LinkedIn Country Codes (e.g., `["US", "FR"]`) of the person, not the company HQ. Use `["WORLD"]` or an empty list for no filter. Up to 50 values. Default: `["WORLD"]`.
`include_headline_search`	`boolean`	No	If `true`, keywords also match against the person’s LinkedIn headline, not just their formal job title. The “About” section is not searched. Default: `false`.

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.

Matching Rules

Current roles only. The waterfall only returns people who hold a current role at the target company. With include_headline_search: true, the headline can match, but the person must still work at the company now.
Keywords, not substrings. Each phrase in include_title and exclude_title follows the Keyword Filters rules: every word must appear, in any order, as a whole word. There is no stemming, no synonym and no abbreviation expansion, so "Demand Gen" does not match "Demand Generation". To cover variants, list each form as its own phrase, for example ["VP Demand Gen", "VP Demand Generation", "Vice President Demand Generation"].
exclude_title and the headline. When include_headline_search is true, an exclude_title phrase that appears in the headline also removes the person, not only one that appears in the job title.
No level or function filter. The waterfall has no job_level or job_function parameter. Seniority comes from the words in include_title and from the order of your tiers. To filter the people of one company by level and function, use Employee Finder.

Response Schema

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

{
  "results_length": 3,
  "results": [
    {
      "icp": 1,
      "ranking": 1,
      "person": {
        "first_name": "Jane",
        "last_name": "Doe",
        "full_name": "Jane Doe",
        "headline": "VP of Sales | @Acme Corp",
        "about_me": "Scaling B2B revenue teams...",
        "location": {
          "city": "New York",
          "state_code": "NY",
          "country_code": "US",
          "continent": "North America",
          "postal_code": null,
          "street_address": null
        },
        "linkedin_url": "https://www.linkedin.com/in/janedoe",
        "connections_count": 2500,
        "profile_picture_url": null,
        "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,
            "job_contract_type": null,
            "job_work_arrangement": null
          }
        ],
        "education": [],
        "skills": ["B2B Sales", "SaaS", "Revenue Operations"],
        "certifications": []
      }
    },
    {
      "icp": 2,
      "ranking": 2,
      "person": {
        "first_name": "Alice",
        "last_name": "Martin",
        "full_name": "Alice Martin",
        "headline": "Sales Director | @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.
`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`	Built from the first position as `<job title> \| @<employer>`. It is not the LinkedIn headline that `include_headline_search` matches, so don’t look for your matched words here.
`about_me`	`string \| null`	LinkedIn “About” section.
`location`	`object`	Location with `city`, `state_code`, `country_code`, `continent`, `postal_code`, `street_address`.
`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`	Always `null`. Kept in the response so existing clients do not break.
`experiences`	`array`	Work history. Each entry: `job_title`, `company_linkedin_url`, `job_start_date`, `job_end_date`, `job_is_current`, `job_contract_type`, `job_work_arrangement`, `job_location`.
`education`	`array`	Education history. Each entry: `school_name`, `degree`, `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 up to max_results people (default 10, max 100), best tier first. If your need is different, pick the right tool:

Use Case	Best Endpoint
Best-fit decision-makers at a known company, in your priority order	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)

Matching Rules

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)

​Matching Rules

​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)

Matching Rules

Response Schema

Top-Level Fields

Result Fields (`results[]`)

Person Object (`results[].person`)

Waterfall vs. the Rest of the People Search Family