Skip to main content
POST
/
v1
/
prospector
Prospector Launcher
curl --request POST \
  --url https://api.waterfall.io/v1/prospector \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "domain": "waterfall.io",
  "title_filter": "founder OR ceo",
  "limit": 10,
  "include_phones": false
}
'
{
  "job_id": "dae884ce-50aa-4208-b24f-f30687a00368",
  "start_date": "2024-01-15T12:00:00.000000+00:00"
}
Prospector OverviewYou input: Target account domain or LinkedIn URL, plus title filters (Boolean expression or named lists)You get: Contacts with verified emails, job titles, location, LinkedIn profiles, and phone numbers (optional)

​
Supported input combinations

You can launch Prospector in two main modes:
Use caseRequired fieldsNotes
Single Boolean filterdomain and title_filterBest when you already have a well-defined Boolean title expression.
Multiple named filtersdomain and title_filters (1–5)Use when you want to try several personas (for example founders, sales, marketing) in priority order.

Authorizations

​
x-api-key
string
header
required

To access the API, provide your API key in x-api-key.

Body

application/json

Prospector Launcher request payload.

Target a company with domain (required) and one of title_filter or title_filters (required). Optional: location_name, location_country, location_countries, limit, include_phones, verified_only, webhook_url, and custom_fields.

​
domain
string

The domain where you want to find contacts. It can be a plain domain or a full URL; Waterfall automatically extracts the company domain.

Required string length: 2 - 500
Example:

"waterfall.io"

​
company_name
string

The name of the company where you want to find contacts.

Required string length: 1 - 500
Example:

"Waterfall"

​
linkedin
string | null

Company LinkedIn URL or ID/handle (for example google from https://www.linkedin.com/company/google/). Recommended input to maximize coverage.

Maximum string length: 500
Example:

"waterfall-io"

​
title_filter
string | null

Single title filter expression. One of title_filter or title_filters is required.

Required string length: 2 - 10000
Example:

"( (manager OR director) AND (sales OR marketing) ) AND NOT ( project manager OR sales manager)"

​
title_filters
object[]

Allows multiple title filters in order. Used only if title_filter is not present. One of title_filter or title_filters is required.

Required array length: 1 - 5 elements
Example:
[
  {
    "name": "founders",
    "filter": "founder OR co-founder OR ceo"
  }
]
​
location_name
string

Location of the contact's current address. Supports city/region/country and partial forms (for example, region only).

Required string length: 1 - 200
Example:

"San Francisco, California, United States"

​
location_country
string | null

Country of the contact's current address. Use full country names (for example, United States or France).

Required string length: 1 - 200
Example:

"United States"

​
location_countries
(string | null)[] | null

List of possible countries of the contact's current address. If it is present it will be used instead of location_country.

Maximum array length: 50

Country of the contact's current address. Use full country names (for example, United States or France).

Required string length: 1 - 200
Example:

"United States"

Example:
["United States", "Canada"]
​
excluded_names
string[] | null

The list of names to exclude from results

Maximum array length: 100
Example:
["Bill Gates", "Steve Ballmer"]
​
limit
integer<int32> | null
default:10

Maximum number of contacts returned per company for a search.

Required range: 1 <= x <= 500
Example:

3

​
include_phones
boolean
default:false

Default false. If set to true, Waterfall runs advanced phone enrichment to maximize phone coverage and additional charges may apply when numbers are found.

​
verified_only
boolean | null
default:true

If not present or set to true, Waterfall will only return safe to send emails. If present and set to false, Waterfall will return both safe to send and catch-all emails. All emails including catch-all ones are verified to remove invalid, role, and spam-trap emails.

​
webhook_url
string<uri>

Optional webhook callback URL. If supplied, Waterfall POSTs the same payload returned by the Finder endpoint when processing completes. If your webhook responds with 429, 500, 502, or 504, Waterfall retries delivery up to 5 times with exponential backoff.

Maximum string length: 2083
Example:

"https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1"

​
custom_fields
object

Any custom key-value pairs echoed back in the Prospector Finder output (useful for correlating internal source metadata).

Example:
{
  "tenantId": "0e9d26b7-cdb5-4d95-b248-59ac389d2e8a",
  "workflowId": "ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4",
  "waterfallRequestId": "1b49c542-f47a-406b-a95f-a1859d1461af"
}

Response

Prospector successfully launched.

Response returned when a prospector job is successfully launched.

​
job_id
string<uuid>
required

A UUID.

Example:

"7d44db58-5de3-4e92-a2fb-8325d12c2e8b"

​
start_date
string<date-time>
required

A date time in ISO 8601 format.

Example:

"2025-02-05T15:46:35.771Z"