Waterfall ICP Search

Tiered ICP contact waterfall. Checks tier 1 first, then 2, then 3, and stops when a tier returns contacts.

Endpoint

POST /api/v1/contacts/waterfall-icp

Authentication

All requests require the X-Satellyte-API-Key header. See Quickstart.

Request body

Field	Type	Required	Notes
`company_domain`	string	Conditional	Required if `company_linkedin_url` is absent.
`company_linkedin_url`	string	Conditional	LinkedIn company URL.
`max_results`	number	No	1 to 25 contacts per matched tier. Defaults to 3.
`cascade`	object[]	Yes	Ordered role tiers to try. Min 1, max 10.
`cascade[].role`	string	Yes	Role label (`decision_maker`, `budget_owner`, `influencer`).
`cascade[].include_titles`	string[]	Yes	Titles to include for this tier.
`cascade[].exclude_titles`	string[]	No	Titles to exclude.
`cascade[].locations`	string[]	No	Locations or `WORLD`.

cURL

curl -i -X POST "https://api-staging.satellyte.ai/api/v1/contacts/waterfall-icp" \
  -H "X-Satellyte-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_domain": "stripe.com",
    "max_results": 3,
    "cascade": [
      {
        "role": "decision_maker",
        "include_titles": ["Chief Revenue Officer", "VP Sales", "Head of Sales"],
        "exclude_titles": ["assistant", "intern", "junior"],
        "locations": ["WORLD"]
      },
      {
        "role": "budget_owner",
        "include_titles": ["CEO", "Founder", "Co-Founder"],
        "locations": ["WORLD"]
      },
      {
        "role": "influencer",
        "include_titles": ["Sales Manager", "Growth Manager", "RevOps"],
        "locations": ["WORLD"]
      }
    ]
  }'

Response (200)

{
  "data": {
    "matched": false,
    "matched_tier": null,
    "matched_role": null,
    "items": [],
    "waterfall": [
      { "tier": 1, "role": "decision_maker", "status": "not_matched", "result_count": 0 },
      { "tier": 2, "role": "budget_owner",   "status": "not_matched", "result_count": 0 },
      { "tier": 3, "role": "influencer",     "status": "not_matched", "result_count": 0 }
    ]
  }
}

Response fields

Field	Type	Notes
`matched`	boolean	Whether any tier returned contacts.
`matched_tier`	number \| null	1-indexed tier that produced results.
`matched_role`	string \| null	Role label of the matched tier.
`items[]`	object[]	Contacts from the matched tier (same shape as `/contacts/find`).
`waterfall[]`	object[]	Per-tier outcome. Each entry has `tier`, `role`, `status` (`matched`/`not_matched`), `result_count`.