{"uid":"cap_Kc7ahJhmWgxo79IUm3Vw-","slug":"agents-blitz-api-ai-waterfall-icp-search-16e9dfc8","name":"Waterfall ICP Search","description":"Find the best decision-maker at a target company using a prioritized cascade hierarchy.","url":"https://agents.blitz-api.ai/v2/search/waterfall-icp-keyword?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","required":["company_linkedin_url","cascade"],"properties":{"cascade":{"type":"array","items":{"type":"object","required":["include_title"],"properties":{"location":{"type":"array","items":{"type":"string"},"default":["WORLD"],"example":["WORLD"],"maxItems":50,"description":"Country codes of the person (not the company headquarters). Use 'WORLD' or an empty list for no restriction (up to 50 values)."},"exclude_title":{"type":"array","items":{"type":"string"},"example":["assistant","intern","junior"],"maxItems":50,"description":"Job title phrases that disqualify a person, with the same matching rules as `include_title` (up to 50). Also checked against the LinkedIn headline when `include_headline_search` is `true`."},"include_title":{"type":"array","items":{"type":"string"},"example":["Marketing Director","Head Marketing","Chief Marketing Officer"],"maxItems":50,"minItems":1,"description":"Job title phrases to match, OR'd together (1 to 50). All words of a phrase must be in the title, in any order, as whole words, with no stemming or synonyms. Wrap a phrase in square brackets for an exact match. See [Keyword Filters](/guide/reference/normalization/filters)."},"include_headline_search":{"type":"boolean","default":false,"example":false,"description":"When true, also searches the LinkedIn headline (not the About section) in addition to the job title. The person must still hold a current role at the company."}},"additionalProperties":false},"maxItems":10,"minItems":1,"description":"Ordered list of search tiers (1 to 10). Tier 1 fills `max_results` first. If it finds fewer people than `max_results`, the next tier fills the slots that are left, and so on, until `max_results` is reached or no tiers are left. People already found in an earlier tier are not returned twice."},"max_results":{"type":"number","default":10,"example":10,"maximum":100,"minimum":1,"description":"Maximum number of results to return."},"company_linkedin_url":{"type":"string","example":"https://www.linkedin.com/company/openai"},"profile_min_connections":{"type":"number","default":0,"example":0,"minimum":0,"description":"Minimum number of LinkedIn connections a profile must have to be returned."}},"additionalProperties":false},"responseSchema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"icp":{"type":"number","description":"Index (1-based) of the cascade tier that matched this result."},"person":{"type":"object","properties":{"skills":{"type":"array","items":{"type":"string"}},"about_me":{"type":["string","null"]},"headline":{"type":["string","null"],"description":"Built from the person's first position as \"<job title> | @<employer>\", not the free-text headline on the LinkedIn profile."},"location":{"type":"object","properties":{"city":{"type":["string","null"]},"continent":{"type":["string","null"]},"state_code":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country_code":{"type":["string","null"]},"street_address":{"type":["string","null"]}}},"nickname":{"type":["string","null"]},"education":{"type":"array","items":{"type":"object","properties":{"degree":{"type":"string"},"end_date":{"type":["string","null"],"format":"date"},"start_date":{"type":["string","null"],"format":"date"},"school_name":{"type":["string","null"]}}}},"full_name":{"type":"string"},"last_name":{"type":"string"},"first_name":{"type":"string"},"experiences":{"type":"array","items":{"type":"object","properties":{"job_title":{"type":"string"},"company_name":{"type":["string","null"]},"job_end_date":{"type":["string","null"],"format":"date"},"job_location":{"type":"object","properties":{"city":{"type":["string","null"]},"state_code":{"type":["string","null"]},"country_code":{"type":["string","null"]}}},"company_domain":{"type":"string"},"job_is_current":{"type":"boolean"},"job_start_date":{"type":["string","null"],"format":"date"},"job_description":{"type":["string","null"]},"job_contract_type":{"type":["string","null"]},"company_linkedin_id":{"type":"string"},"company_linkedin_url":{"type":"string"},"job_work_arrangement":{"type":["string","null"]}}}},"linkedin_url":{"type":"string"},"certifications":{"type":"array","items":{"type":"object","properties":{"url":{"type":["string","null"]},"name":{"type":"string"},"authority":{"type":"string"}}}},"civility_title":{"type":["string","null"]},"connections_count":{"type":"number"},"profile_picture_url":{"type":["string","null"],"description":"Always null. The field is kept in the response so existing clients do not break."}}},"ranking":{"type":"number","description":"Overall rank of this result across all tiers."}}}},"fair_usage":{"type":"object","required":["records_used","records_remaining","next_reset_at","request_id"],"properties":{"rate_limit":{"type":"object","required":["requests_per_second","remaining_this_second"],"properties":{"requests_per_second":{"type":"number","examples":[10],"description":"Requests this API key may send per second. Set by your plan."},"remaining_this_second":{"type":"number","examples":[9],"description":"Requests left in the current one-second window."}},"description":"Absent on endpoints that are not rate limited.","additionalProperties":false},"request_id":{"type":"string","examples":["019bae09-0055-7441-b2ea-16086e499219"],"description":"Quote this id when you contact support."},"records_used":{"type":"number","examples":[3],"description":"Records this request consumed, after reconciliation against the results actually returned."},"next_reset_at":{"anyOf":[{"type":"string"},{"type":"null"}],"examples":["2026-09-29T10:25:23.155Z"],"description":"When the record balance resets. Null on an unlimited plan."},"records_remaining":{"anyOf":[{"type":"number"},{"type":"string","const":"unlimited"}],"examples":[9913547],"description":"Records left on the plan after this request."}},"description":"Record usage, rate limit, and tracing data for this request.","additionalProperties":false},"max_results":{"type":"number"},"results_length":{"type":"number"},"company_linkedin_url":{"type":"string"}}},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"unknown","displayCostAsset":"USD","priceDynamic":true,"priceHint":null,"priceStatus":"unprobed","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"unknown","summary":"price unknown","primary":{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_CCZHK94rZhqr9VNk7yvQ6","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"unknown","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":"agents.blitz-api.ai","brandSlug":"agents-blitz-api-ai-x402","brandBaseUrl":"https://agents.blitz-api.ai","brandDocsUrl":null,"whatItDoes":"Finds the best-matching decision-maker at a target company by searching through a prioritized cascade of job title tiers, returning the top people from the highest-priority tier with results.","exampleAgentPrompt":"Find the best decision-maker at Salesforce (https://www.linkedin.com/company/salesforce/) using this priority list: first look for a Chief Marketing Officer or VP Marketing, then fall back to a Marketing Director or Head of Marketing, then a Marketing Manager — return up to 3 contacts.","exampleUseCases":[{"title":"Outbound sales prospect identification","prompt":"I'm targeting Stripe for outbound sales. Find me the best contact using this priority order: first a Chief Revenue Officer or VP Sales, then a Head of Sales or Sales Director, then a Sales Manager. Use their LinkedIn at linkedin.com/company/stripe and return up to 1 result."},{"title":"ABM campaign decision-maker lookup","prompt":"I need to find the top marketing decision-maker at HubSpot (linkedin.com/company/hubspot) for an ABM campaign. Check first for a CMO or Chief Marketing Officer, then a VP of Marketing or Marketing VP, then a Marketing Director — give me up to 2 results and exclude anyone with intern or assistant in their title."},{"title":"Recruiting outreach to engineering leaders","prompt":"Help me find the right engineering leader to contact at Notion (linkedin.com/company/notion-hq). Try first for a CTO or VP Engineering, then Head of Engineering or Engineering Director, then a Senior Engineering Manager — I only want people based in the US, return the top 1 match."}],"resultDescription":"Returns an array of matched professional profiles, each tagged with the cascade tier (ICP index) that matched them. Each profile includes full name, LinkedIn URL, constructed headline, current and past work experiences (with job titles, company names, dates, and location), location details, skills, education history, about/bio text, and certifications. Results are ordered by cascade tier priority, with higher-priority tier matches appearing first.","failureModes":["Company LinkedIn URL not found or invalid — returns empty results array","No people match any tier in the cascade — returns empty results array","All matching people already excluded by exclude_title filters — returns fewer results than max_results","Cascade tiers all have very broad titles leading to unexpected matches","Rate limiting or authentication errors if API key is missing or exhausted credits"],"whenToPreferThis":"Choose this endpoint when you already know the target company and want the single best-matching decision-maker from a ranked list of acceptable job titles — it is purpose-built for account-based outreach where you have a preferred ICP title hierarchy. Use it instead of general People Search when you need the highest-priority matching contact at one specific company, not a broad list across many companies. It is especially valuable when your ICP has a fallback logic (e.g., prefer CMO, but accept VP Marketing if no CMO exists).","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-14T00:35:00.440Z","isFirstParty":false,"canonicalSlug":"agents-blitz-api-ai-waterfall-icp-search-16e9dfc8"}