Skip to main content
POST
/
v1
/
enrichment
/
contact
curl --request POST \
  --url https://api.waterfall.io/v1/enrichment/contact \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "email": "john.doe@waterfall.io",
  "include_phones": false
}
'
{
  "job_id": "dae884ce-50aa-4208-b24f-f30687a00368",
  "start_date": "2024-01-15T12:00:00.000000+00:00"
}
Contact Enrichment OverviewYou input: Professional/personal email, LinkedIn URL/slug, or name + domainYou get: Verified email, job title, current company, location, employment history, and phone numbers (optional)
This is an asynchronous endpoint. Use the returned job_id with Contact Enrichment Finder to retrieve results. Jobs typically complete in under 10 seconds.We recommend passing webhook_url for a smoother integration — Waterfall will POST the result directly to your endpoint as soon as the job is ready, so you don’t need to poll.

​
Input strategies

Pick the identifier you have. Waterfall applies them in priority order if you send more than one.
PriorityStrategyRequired fieldsBest for
1EmailemailHighest accuracy. Use a professional email when available.
2LinkedInlinkedinUse the profile slug or full URL (/in/john-doe).
3Full name + domainfull_name + domainWhen you have no email or LinkedIn.
4Split name + domainfirst_name + last_name + domainSame as above, split across two fields.
Only one strategy is evaluated per request (highest priority wins). If you send email + linkedin, only the email path runs.

​
Business notes

Add your internal notes here — pricing tier, credit cost per call, SLA guarantees, data sources used, etc.
  • Credit cost: charged per successful enrichment (contact returned), not per launch
  • Phone numbers: set include_phones: true to also run phone enrichment — note this may apply additional charges
  • Catch-all emails: by default Waterfall returns only verified safe-to-send addresses; to include catch-all results set verified_only: false in a supported endpoint

​
Webhook

Pass webhook_url to receive the Finder payload automatically when enrichment completes — avoids the need to poll. 
{
  "email": "jane.doe@acme.com",
  "webhook_url": "https://your-app.com/webhooks/waterfall"
}

​
Passing custom metadata

Use custom_fields to attach internal IDs or source labels. These are echoed back in the Finder response unchanged — useful for correlating enrichment results with your CRM records. 
{
  "email": "jane.doe@acme.com",
  "custom_fields": {
    "crm_id": "001ABC",
    "source": "outbound-q1"
  }
}

​
Next step

After launching, call Contact Enrichment Finder with the job_id: 
GET /v1/enrichment/contact?job_id={job_id}

Authorizations

​
x-api-key
string
header
required

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

Body

application/json

Contact enrichment payload: provide one identifier strategy (linkedin, email, full_name + domain, or first_name + last_name + domain) plus optional include_phones, webhook_url, and custom_fields.

Request payload to launch a contact enrichment job.

​
linkedin
string | null
required

Company LinkedIn URL or ID/handle (for example google from https://www.linkedin.com/company/google/). Recommended input to maximize coverage.

Maximum string length: 500
Example:

"waterfall-io"

​
full_name
string | null

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

Maximum string length: 250
Example:

"John Doe"

​
first_name
string | null

First name of the contact.

Maximum string length: 100
Example:

"John"

​
last_name
string | null

Last name of the contact.

Maximum string length: 100
Example:

"Doe"

​
domain
string

The domain where you want to find contacts. It can be a plain domain or a full URL; Waterfall automatically extracts the company domain.

Required string length: 2 - 500
Example:

"waterfall.io"

​
email
string<email>

Professional or personal email address.

Maximum string length: 254
Example:

"john.doe@waterfall.io"

​
include_phones
boolean
default:false

Default false. If set to true, Waterfall runs advanced phone enrichment to maximize phone coverage and additional charges may apply when numbers are found.

​
webhook_url
string<uri>

Optional webhook callback URL. If supplied, Waterfall POSTs the same payload returned by the Finder endpoint when processing completes. If your webhook responds with 429, 500, 502, or 504, Waterfall retries delivery up to 5 times with exponential backoff.

Maximum string length: 2083
Example:

"https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1"

​
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

Contact enrichment job successfully launched.

Response returned when a contact enrichment job is successfully launched.

​
job_id
string<uuid>
required

A UUID.

Example:

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

​
start_date
string<date-time>
required

A date time in ISO 8601 format.

Example:

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