Skip to main content
POST
Search Contact Launcher
Search Contact OverviewYou input: LinkedIn URL, company identity, or persona filters (title, department, seniority, location, hire date)You get: Contact profiles with name, title, company, location, and employment history — no contact channels
Search Contact returns results synchronouslyoutput.persons is included directly in the response. There is no separate polling step.
This endpoint doesn’t return contact channels (email, phone). It returns profile data only. To retrieve contact channels for a person, pass their linkedin_url as the linkedin field in Contact Enrichment Launcher.

Search modes

For details on title filters, experience dates, and department/seniority filters, see Search Contact Filters.

Authorizations

x-api-key
string
header
required

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

Body

application/json

Search Contact request payload with filters and pagination options.

Request payload for Search Contact. Search mode must be one of: 1) contact_linkedin 2) company-specific search with one of domain, company_linkedin, company_name 3) company-set search with one of company_location_countries, company_industries, or company_employee_ranges (in this mode, experience_start_date or experience_start_date_new_hire is required, and one of title_filters or title_lists is required).

contact_linkedin
string | null
required

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

Required string length: 3 - 500
Example:

"waterfall-io"

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: 4 - 500
Example:

"waterfall.io"

company_linkedin
string | null

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

Required string length: 3 - 500
Example:

"waterfall-io"

company_name
string

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

Required string length: 3 - 500
Example:

"Waterfall"

excluded_names
(string | null)[] | null

Names to exclude from results.

Maximum array length: 200

Full name of the contact. Providing first_name and last_name is preferable when both are available.

Required string length: 4 - 250
Example:

"John Doe"

Example:
included_names
(string | null)[] | null

If provided, restrict results to these names.

Maximum array length: 100

Full name of the contact. Providing first_name and last_name is preferable when both are available.

Required string length: 4 - 250
Example:

"John Doe"

Example:
title_filters
object[] | null

Boolean title filters.

Maximum array length: 5
Example:
title_lists
object[] | null

Named title lists.

Maximum array length: 5
Example:
departments
enum<string>[] | null

Contact department filters.

Contact department returned on person payloads.

Available options:
Leadership,
Engineering,
Product Management,
Sales,
Marketing,
Customer Success,
Finance,
Accounting,
Legal,
Human Resources,
Information Technology,
Operations,
Education,
Other
Required string length: 5 - 22
Example:
seniorities
enum<string>[] | null

Contact seniority filters.

Contact seniority returned on person payloads.

Available options:
Owner,
CXO,
Partner,
Vice President,
Director,
Manager,
Senior,
Entry,
Other
Required string length: 3 - 14
Example:
location_countries
(string | null)[] | null

Contact location countries.

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:
company_location_countries
(string | null)[] | null

Company location countries.

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:
company_industries
string[] | null

Company industries.

Maximum array length: 50

LinkedIn industry filter value. Use title-case industry names from the supported industry list: https://waterfall-io-public.s3.us-east-1.amazonaws.com/industries.txt.

Required string length: 5 - 57
Example:
company_employee_ranges
enum<string>[] | null

Company employee size ranges.

Maximum array length: 8

LinkedIn employee-size bucket.

Available options:
1-10,
11-50,
51-200,
201-500,
501-1000,
1001-5000,
5001-10000,
10001+
Example:
experience_start_date
string<date> | null

Find contacts who started their current role on or after the specified date (YYYY-MM-DD).

Example:

"2024-01-01"

experience_start_date_new_hire
string<date> | null

Find new hires who started their current role on or after the specified date (YYYY-MM-DD).

Example:

"2025-01-01"

page_number
integer<int32>
default:1

Page number for paginated Search Contact results.

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

1

page_size
integer<int32>
default:10

Number of contacts to return per page in Search Contact.

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

10

custom_fields
object | null

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

Example:

Response

Search Contact result returned successfully.

Search Contact response with job state, input, and optional output.

status
enum<string>
required

The status of the job.

Available options:
RUNNING,
SUCCEEDED,
FAILED,
TIMED_OUT,
ABORTED
Example:

"RUNNING"

start_date
string<date-time>
required

A date time in ISO 8601 format.

Example:

"2025-02-05T15:46:35.771751+00:00"

input
object
required
Example:
stop_date
string<date-time>

A date time in ISO 8601 format.

Example:

"2025-02-05T15:46:35.771751+00:00"

output
object

Search Contact output payload.

Example: