Skip to main content
POST
/
v1
/
enrichment
/
phone
curl --request POST \
  --url https://api.waterfall.io/v1/enrichment/phone \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "linkedin": "https://www.linkedin.com/in/jane-doe-abc123/"
}
'
{
  "job_id": "dae884ce-50aa-4208-b24f-f30687a00368",
  "start_date": "2024-01-15T12:00:00.000000+00:00"
}
Phone Enrichment OverviewYou input: LinkedIn URL/slug, email, or name + domainYou get: Mobile and direct-dial phone numbers in E.164 format
This is an asynchronous endpoint. Use the returned job_id with Phone Enrichment Finder to retrieve results.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.
You are only charged when a phone number is successfully returned.

​
Input strategies

PriorityStrategyRequired fieldsNotes
1LinkedInlinkedinSignificantly better results. Use full URL or slug.
2EmailemailProfessional email gives higher success rate than personal.
3Full name + domainfull_name + domainFallback when no LinkedIn or email available.
4Split name + domainfirst_name + last_name + domainSame as above, split across two fields.
If a previous attempt with LinkedIn was unsuccessful, retry with a professional email — the two methods use different underlying data sources.

​
Business notes

Add your internal notes here — pricing tier, credit cost per successful number, SLA guarantees, etc.
  • Billing: charged per phone number returned, not per launch
  • Format: all numbers returned in E.164 format (e.g. +14155550123)
  • Coverage: mobile_phone returns the primary number; phone_numbers is the full list

​
Next step

After launching, call Phone Enrichment Finder with the job_id: 
GET /v1/enrichment/phone?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

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

Request payload to launch a phone 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"

​
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

Phone enrichment job successfully launched.

Response returned when a phone 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"