Skip to main content
GET
/
v1
/
prospector
Prospector Finder
curl --request GET \
  --url https://api.waterfall.io/v1/prospector \
  --header 'x-api-key: <api-key>'
{
  "status": "SUCCEEDED",
  "start_date": "2024-06-18T13:53:21.181000+00:00",
  "stop_date": "2024-06-18T13:53:26.014000+00:00",
  "input": {
    "task": {
      "domain": "acme.com",
      "company_name": null,
      "webhook_url": null,
      "limit": 10,
      "custom_fields": null,
      "job_id": "413b35ce-572e-4d3a-bff6-e52d4542361d",
      "context_id": "413b35ce-572e-4d3a-bff6-e52d4542361d"
    }
  },
  "output": {
    "company": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "domain": "acme.com",
      "company_name": "Acme Corp",
      "website": "https://www.acme.com/",
      "linkedin_id": "acme-corp",
      "linkedin_url": "https://www.linkedin.com/company/acme-corp/",
      "size": "501-1000"
    },
    "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/",
        "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": "jane.doe@acme.com",
        "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": true,
        "email_confidence": "high",
        "email_verified_status": "safe",
        "domain_age_days": null,
        "smtp_provider": "Google",
        "mx_record": "aspmx.l.google.com"
      }
    ]
  }
}
Use the job_id returned by Prospector Launcher to fetch state and results.

​
Polling vs webhook

If you passed webhook_url when launching the job, you don’t need to call this endpoint at all — Waterfall will automatically POST the result to your URL as soon as the job is ready. If you didn’t use a webhook, poll this endpoint until status is SUCCEEDED: 
GET /v1/prospector?job_id={job_id}
Use short exponential backoff — start with a 5s delay, then 10s, then 20s.

​
Job states

StatusMeaning
RUNNINGJob is still processing. Continue polling.
SUCCEEDEDJob is complete. Results are in output.

​
What you get

The output object contains two keys:
FieldDescription
output.companyCompany profile for the target domain — name, LinkedIn, size, website
output.personsArray of contacts found. Each person uses the standard Person object with full fields: email, title, location, seniority, experiences, and more
The number of persons returned is controlled by the limit parameter set at launch (default 10, max 500).

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

Prospector job state, input, and any available output data.

Finder response with prospector job status, 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
​
stop_date
string<date-time>

A date time in ISO 8601 format.

Example:

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

​
output
object