Prospector Launcher
Launch a contact search using domain, LinkedIn URL/ID, or company name.
Supported input combinations
You can launch Prospector in two main modes:Authorizations
To access the API, provide your API key in x-api-key.
Body
Request payload for Prospector Launcher. Includes required targeting fields (domain + title_filter or title_filters) and optional company identifier, location filters, limit, include_phones, verified_only, webhook_url, and custom_fields. Because processing is asynchronous, use the Finder endpoint or provide webhook_url for callback delivery.
- Option 1
- Option 2
Request payload to launch a prospector job.
The domain where you want to find contacts. It can be a plain domain or a full URL; Waterfall automatically extracts the company domain.
4 - 500"waterfall.io"
Single title filter expression. One of title_filter or title_filters is required.
2 - 10000"( (manager OR director) AND (sales OR marketing) ) AND NOT ( project manager OR sales manager)"
The name of the company where you want to find contacts.
3 - 500"Waterfall"
Company LinkedIn URL or ID/handle (for example google from https://www.linkedin.com/company/google/). Recommended input to maximize coverage.
3 - 500"waterfall-io"
Allows multiple title filters in order. Used only if title_filter is not present. One of title_filter or title_filters is required.
1 - 5 elementsLocation of the contact's current address. Supports city/region/country and partial forms (for example, region only).
1 - 200"San Francisco, California, United States"
Country of the contact's current address. Use full country names (for example, United States or France).
1 - 200"United States"
List of possible countries of the contact's current address. If it is present it will be used instead of location_country.
50Country of the contact's current address. Use full country names (for example, United States or France).
1 - 200"United States"
The list of names to exclude from results
200Full name of the contact. Providing first_name and last_name is preferable when both are available.
4 - 250"John Doe"
Maximum number of contacts returned per company for a search.
1 <= x <= 5003
Default false. If set to true, Waterfall runs advanced phone enrichment to maximize phone coverage and additional charges may apply when numbers are found.
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.
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. Waterfall includes X-Webhook-Signature containing a compact JWT when webhook signing configuration is available. The JWT protected header contains alg: "EdDSA", kid, and typ: "JWT". Its claims contain iat, exp, jti, job_id, body_hash, and body_hash_alg: "sha-256". body_hash is the unpadded base64url-encoded SHA-256 digest of the exact raw request body bytes. The JSON body is unchanged by signing. Signatures expire exactly 15 minutes after iat; receivers should reject expired signatures. If signing configuration is unavailable or invalid, Waterfall preserves backward compatibility by sending the callback unsigned without X-Webhook-Signature.
2083"https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1"
Optional custom key-value metadata echoed on job input and output (useful for correlating internal source metadata). On create requests, omit the field or send JSON null when no custom fields are needed; both are stored as {}. When present, the value must be a JSON object with keys matching ^[A-Za-z0-9_-]+$ and values that are a string (max 1000 characters), number, or boolean. Empty string, arrays, and other non-object types return HTTP 400. On job GET responses, input.task.custom_fields is always an object ({} or populated).