Skip to main content
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.
Waterfall ICP Search (POST /v2/search/waterfall-icp-keyword) finds the best decision-makers at a known company, in your order of preference. It takes the company’s LinkedIn URL and a cascade of 1 to 10 job title tiers, fills max_results tier by tier, and returns each person with the tier that matched. Use it to reach the right contacts, not every employee.
API Reference: the Waterfall ICP (Keyword) endpoint, with the full request/response schema and a try-it console.
In modern B2B growth, more leads is not the goal. Better leads are. 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.
1

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

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

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. A fallback tier such as the CEO or founder makes 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:
  1. Tier 1: Get the Marketing Director/CMO (Global).
  2. Tier 2: If there are slots left, add a Growth Manager (Global).
  3. Tier 3: If there are still slots left, add a Brand/Comms Director (Global).
  4. Tier 4: Then try a broader keyword search in North America only.
  5. Tier 5: Finally, add the CEO.

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 the BlitzAPI B2B data infrastructure to deliver results instantly.
  • Availability: every plan. Each result returned counts as one record against your fair use policy; a call that finds nothing counts nothing.
  • Latency: < 600ms

Request Parameters

Top-Level Parameters

Cascade Object Parameters (per tier)

Country Codes: Use 2-letter ISO 3166-1 alpha-2 codes (e.g., US, GB, FR). A value of any other length returns a 422. See the Country Codes reference for the full list.

Matching Rules

  • Current roles by default. Unless a tier sets include_past_jobs: true, that tier 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.
  • Past jobs. With include_past_jobs: true, a tier also finds people by a job they held before at the company. The company and the title filters of the tier must then hold in the same job, and experiences carries the matched job with job_is_current set. A person is returned once, and a current job is preferred to a past one. Set include_active_jobs: false in the tier to search past jobs only.
  • 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:

Top-Level Fields

Result Fields (results[])

Person Object (results[].person)

How to use icp and ranking together:
  • 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:

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.

Waterfall ICP API: product overview

Use cases, coverage, and the endpoints it chains with.