Search Contact Finder

curl --request GET \
  --url https://api.waterfall.io/v1/search/contact \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.waterfall.io/v1/search/contact', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.waterfall.io/v1/search/contact",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.waterfall.io/v1/search/contact"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.waterfall.io/v1/search/contact")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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",
        "Vice President"
      ],
      "page_number": 1,
      "page_size": 25,
      "custom_fields": {},
      "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
      }
    ],
    "usage": {
      "total_usd": 0.1,
      "balance_remaining_usd": 99.9,
      "persons_count": 1,
      "persons_usd": 0.1,
      "phones_count": 0,
      "phones_usd": 0,
      "companies_count": 0,
      "companies_usd": 0
    }
  }
}

GET

contact

Search Contact Finder

curl --request GET \
  --url https://api.waterfall.io/v1/search/contact \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.waterfall.io/v1/search/contact', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.waterfall.io/v1/search/contact",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.waterfall.io/v1/search/contact"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.waterfall.io/v1/search/contact")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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",
        "Vice President"
      ],
      "page_number": 1,
      "page_size": 25,
      "custom_fields": {},
      "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
      }
    ],
    "usage": {
      "total_usd": 0.1,
      "balance_remaining_usd": 99.9,
      "persons_count": 1,
      "persons_usd": 0.1,
      "phones_count": 0,
      "phones_usd": 0,
      "companies_count": 0,
      "companies_usd": 0
    }
  }
}

Search Contact returns results synchronously from the launcher. Use this endpoint to re-fetch or audit a previous job — not to poll for completion.

When to use this

Pass the job_id returned by Search Contact Launcher to retrieve the same job state, original input echo, and output.persons without re-running the search.

What you get

The response mirrors the launcher response exactly:

Field	Description
`input.task`	Echo of all request fields plus `job_id` and `context_id`
`output.persons`	Array of contacts found — same shape as the launcher response

Contact channels (professional_email, mobile_phone, etc.) are always null in Search Contact output. Use Contact Enrichment to retrieve them.

Authorizations

x-api-key

string

header

required

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

Query Parameters

job_id

string<uuid>

required

The unique job_id you want to query. This value is returned by the corresponding launcher endpoint.

A UUID.

Example:

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

Response

Search Contact job state, input, and any available output.

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

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.771751+00:00"

output

object

Search Contact output payload.

Show child attributes

Example:

{ "persons": [] }

General guidance

Agent Skills

Prospector

Search Contact

Search Company

Contact Enrichment

Phone Enrichment

Company Enrichment

Job Change

Company Reveal

Company Titles

Email Verification

Webhooks

Account

Support

When to use this

What you get

Authorizations

Query Parameters

Response

​When to use this

​What you get

Authorizations

Query Parameters

Response

When to use this

What you get