Skip to main content
GET
/
v1
/
enrichment
/
contact
Enrichment Contact Finder
curl --request GET \
  --url https://api.waterfall.io/v1/enrichment/contact \
  --header 'x-api-key: <api-key>'
{
  "status": "SUCCEEDED",
  "start_date": "2023-09-20T20:23:36.086988",
  "stop_date": "2023-09-20T20:23:51.892893",
  "input": {
    "task": {
      "linkedin": "https://www.linkedin.com/in/jane-doe-abc123/",
      "first_name": null,
      "last_name": null,
      "full_name": null,
      "domain": null,
      "email": null,
      "webhook_url": null,
      "custom_fields": null,
      "job_id": "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e",
      "context_id": "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
    }
  },
  "output": {
    "person": {
      "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": "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 Contact Enrichment 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 deliver 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/enrichment/contact?job_id={job_id}
Use short exponential backoff — most jobs complete in under 10 seconds. Start with a 2s delay, then 4s, then 8s.

​
Job states

StatusMeaning
RUNNINGJob is still processing. Continue polling.
SUCCEEDEDJob is complete. Output is in the output field.

​
Response shape

The input.task object always echoes back all fields from the original launch request. Fields that were not provided will be null. This is useful for correlating the result with your original request without needing to store it separately.

​
Endpoint details

MetricValue
FlowAsync finder endpoint
Required inputjob_id query parameter
Typical usagePoll until SUCCEEDED, or receive via webhook

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

Contact enrichment job state, input, and any available output person.

Finder response with contact enrichment 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.771751+00:00"

​
input
object
required
​
stop_date
string<date-time>

A date time in ISO 8601 format.

Example:

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

​
output
object