Skip to main content
GET
/
v1
/
search
/
contact
Search Contact Finder
curl --request GET \
  --url https://api.waterfall.io/v1/search/contact \
  --header 'x-api-key: <api-key>'
{
  "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 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:
FieldDescription
input.taskEcho of all request fields plus job_id and context_id
output.personsArray 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.771Z"

​
input
object
required
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.

Example:
{ "persons": [] }