Search Contact Launcher

curl --request POST \
  --url https://api.waterfall.io/v1/search/contact \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "contact_linkedin": "https://www.linkedin.com/in/jane-doe-abc123/",
  "page_number": 1,
  "page_size": 10
}
'

{
  "status": "SUCCEEDED",
  "start_date": "2024-01-15T12:00:00.000000+00:00",
  "stop_date": "2024-01-15T12:00:00.524000+00:00",
  "input": {
    "task": {
      "domain": "acme.com",
      "title_filters": [
        {
          "name": "sales_leaders",
          "filter": "head of sales OR vp sales OR director of sales"
        }
      ],
      "seniorities": [
        "Director",
        "VP"
      ],
      "page_number": 1,
      "page_size": 25,
      "custom_fields": null,
      "job_id": "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e",
      "context_id": "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
    }
  },
  "output": {
    "persons": [
      {
        "id": "e70fc5a3-55d9-43e5-93ea-b9e8210435da",
        "first_name": "Jane",
        "last_name": "Doe",
        "linkedin_id": "jane-doe-abc123",
        "linkedin_url": "https://www.linkedin.com/in/jane-doe-abc123/",
        "about": null,
        "personal_email": null,
        "location": "San Francisco, California, United States",
        "country": "United States",
        "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "company_linkedin_id": "acme-corp",
        "company_name": "Acme Corp",
        "company_domain": "acme.com",
        "professional_email": null,
        "mobile_phone": null,
        "phone_numbers": [],
        "title": "Head of Sales",
        "seniority": "Director",
        "department": "Sales",
        "experiences": [
          {
            "title": "Head of Sales",
            "location": null,
            "company_name": "Acme Corp",
            "company_linkedin_id": "acme-corp",
            "company_linkedin_url": "https://www.linkedin.com/company/acme-corp/",
            "company_domain": "acme.com",
            "start_year": 2021,
            "start_month": 3,
            "start_date": null,
            "end_year": null,
            "end_month": null,
            "end_date": null,
            "is_current": true,
            "description": null
          }
        ],
        "email_verified": null,
        "email_confidence": null,
        "email_verified_status": null,
        "domain_age_days": null,
        "smtp_provider": null,
        "mx_record": null
      }
    ]
  }
}

POST

contact

curl --request POST \
  --url https://api.waterfall.io/v1/search/contact \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "contact_linkedin": "https://www.linkedin.com/in/jane-doe-abc123/",
  "page_number": 1,
  "page_size": 10
}
'

{
  "status": "SUCCEEDED",
  "start_date": "2024-01-15T12:00:00.000000+00:00",
  "stop_date": "2024-01-15T12:00:00.524000+00:00",
  "input": {
    "task": {
      "domain": "acme.com",
      "title_filters": [
        {
          "name": "sales_leaders",
          "filter": "head of sales OR vp sales OR director of sales"
        }
      ],
      "seniorities": [
        "Director",
        "VP"
      ],
      "page_number": 1,
      "page_size": 25,
      "custom_fields": null,
      "job_id": "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e",
      "context_id": "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
    }
  },
  "output": {
    "persons": [
      {
        "id": "e70fc5a3-55d9-43e5-93ea-b9e8210435da",
        "first_name": "Jane",
        "last_name": "Doe",
        "linkedin_id": "jane-doe-abc123",
        "linkedin_url": "https://www.linkedin.com/in/jane-doe-abc123/",
        "about": null,
        "personal_email": null,
        "location": "San Francisco, California, United States",
        "country": "United States",
        "company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "company_linkedin_id": "acme-corp",
        "company_name": "Acme Corp",
        "company_domain": "acme.com",
        "professional_email": null,
        "mobile_phone": null,
        "phone_numbers": [],
        "title": "Head of Sales",
        "seniority": "Director",
        "department": "Sales",
        "experiences": [
          {
            "title": "Head of Sales",
            "location": null,
            "company_name": "Acme Corp",
            "company_linkedin_id": "acme-corp",
            "company_linkedin_url": "https://www.linkedin.com/company/acme-corp/",
            "company_domain": "acme.com",
            "start_year": 2021,
            "start_month": 3,
            "start_date": null,
            "end_year": null,
            "end_month": null,
            "end_date": null,
            "is_current": true,
            "description": null
          }
        ],
        "email_verified": null,
        "email_confidence": null,
        "email_verified_status": null,
        "domain_age_days": null,
        "smtp_provider": null,
        "mx_record": null
      }
    ]
  }
}

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 synchronously — output.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

Mode	Anchor field(s)
Single contact by LinkedIn	`contact_linkedin`
Company-specific search	`domain` or `company_linkedin` or `company_name` — find contacts at a specific company, filtered by title, department, seniority, location, and more
Company-set persona search	One of `company_location_countries` / `company_industries` / `company_employee_ranges` + an experience date + a title filter — discover personas across a set of companies

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 (and one of title_filters or title_lists is required).

domain

string

Domain where you want to search contacts.

Required string length: 4 - 500

Example:

"waterfall.io"

company_linkedin

string | null

Company LinkedIn URL/ID.

Required string length: 3 - 500

Example:

"google"

company_name

string | null

Company name.

Required string length: 3 - 500

Example:

"Google"

contact_linkedin

string | null

Personal LinkedIn URL/ID.

Required string length: 3 - 500

Example:

"https://www.linkedin.com/in/johndoe/"

excluded_names

(string | null)[] | null

Names to exclude from results.

Maximum array length: 100

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

Maximum string length: 250

Example:

"John Doe"

Example:

["Bill Gates", "Steve Ballmer"]

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.

Maximum string length: 250

Example:

"John Doe"

Example:

["Ada Lovelace", "Grace Hopper"]

title_filters

object[] | null

Boolean title filters.

Maximum array length: 5

Show child attributes

Example:

[
  {
    "name": "founders",
    "filter": "founder OR co-founder OR ceo"
  }
]

title_lists

object[] | null

Named lists of exact titles. Each entry in titles is matched exactly against the contact's title. Use title_filters instead for boolean/keyword matching.

Maximum array length: 5

Show child attributes

Example:

[
  {
    "name": "founders",
    "titles": ["founder", "co-founder", "ceo"]
  }
]

departments

string[] | null

Contact department filters.

Example:

["engineering", "marketing"]

seniorities

string[] | null

Contact seniority filters.

Example:

["manager", "director"]

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:

["United States", "Canada"]

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:

["United States", "Canada"]

company_industries

string[] | null

Company industries.

Maximum array length: 50

Example:

[
  "software development",
  "information technology"
]

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:

["201-500", "501-1000"]

headline

string | null

Headline filter applied to profile headline text.

Required string length: 3 - 500

Example:

"demand generation"

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

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

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.771Z"

input

object

required

Show child attributes

Example:

{
  "task": {
    "domain": "waterfall.io",
    "page_number": 1,
    "page_size": 10,
    "job_id": "7d44db58-5de3-4e92-a2fb-8325d12c2e8b",
    "context_id": "7d44db58-5de3-4e92-a2fb-8325d12c2e8b"
  }
}

stop_date

string<date-time>

A date time in ISO 8601 format.

Example:

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

output

object

Search Contact output payload.

Show child attributes

Example:

{ "persons": [] }

Prospector location filter

Search Contact Finder

General guidance

Prospector

Search Contact

Search Company

Contact Enrichment

Phone Enrichment

Company Enrichment

Job Change

Email Verification

Account

Support

Search modes

Authorizations

Body

Response

General guidance

Prospector

Search Contact

Search Company

Contact Enrichment

Phone Enrichment

Company Enrichment

Job Change

Email Verification

Account

Support

​Search modes

Authorizations

Body

Response

Search modes