Skip to main content
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.”
1

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

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

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

ParameterTypeRequiredDescription
company_linkedin_urlstringYesThe full LinkedIn URL of the target company (e.g., "https://www.linkedin.com/company/openai").
cascadearrayYesOrdered array of search tiers (up to 8 levels). The engine tries each tier until max_results is reached.
max_resultsintegerNoMaximum number of people to return across all tiers. Default: 1. Max: 25.

​
Cascade Object Parameters (per tier)

ParameterTypeRequiredDescription
include_titlearrayYesJob titles to match (e.g., ["CEO", "CTO"]). Partial matching — "VP Sales" matches "VP of Sales".
exclude_titlearrayNoTitles to exclude. Use to filter out ["Assistant", "Intern", "Junior"].
locationarrayNoLinkedIn Country Codes (e.g., ["US", "FR"]). Use ["WORLD"] for global. Default: ["WORLD"].
include_headline_searchbooleanNoIf 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

FieldTypeDescription
results_lengthintegerTotal number of results returned. 0 if no match found.
resultsarrayArray of matched people, ordered by cascade priority then relevance.

​
Result Fields (results[])

FieldTypeDescription
icpintegerCascade tier that matched this person. 1 = highest priority (Tier 1), 2 = Tier 2, etc.
rankingintegerOverall relevance rank within the company (1 = most relevant). Use to adapt outreach strategy.
what_matchedarrayWhich filter criteria matched. Each entry has key (e.g., "include_title") and value.
personobjectFull person profile. Pass person.linkedin_url to enrichment endpoints for email/phone.

​
Person Object (results[].person)

FieldTypeDescription
first_namestring | nullFirst name.
last_namestring | nullLast name.
full_namestring | nullFull display name.
headlinestring | nullLinkedIn headline.
about_mestring | nullLinkedIn “About” section.
locationobjectLocation with city, state_code, country_code, continent.
linkedin_urlstringPerson LinkedIn URL — use this as input for /v2/enrichment/email and /v2/enrichment/phone.
connections_countnumber | nullLinkedIn connections count.
profile_picture_urlstring | nullURL to profile picture.
experiencesarrayWork history. Each entry: job_title, company_linkedin_url, job_start_date, job_end_date, job_is_current, job_location.
educationarrayEducation history. Each entry: degree, organization, start_date, end_date.
skillsarrayList of skills (strings).
certificationsarrayList 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+.