Contact Enrichment Launcher
Enrich a contact by email, LinkedIn, or name + domain. Returns a job_id to retrieve results.
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.Business notes
- Credit cost: charged per successful enrichment (contact returned), not per launch
- Phone numbers: set
include_phones: trueto 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: falsein a supported endpoint
Webhook
Passwebhook_url to receive the Finder payload automatically when enrichment completes — avoids the need to poll.
Passing custom metadata
Usecustom_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.
Next step
After launching, call Contact Enrichment Finder with thejob_id:
Authorizations
To access the API, provide your API key in x-api-key.
Body
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.
- Option 1
- Option 2
- Option 3
- Option 4
Request payload to launch a contact enrichment job.
Company LinkedIn URL or ID/handle (for example google from https://www.linkedin.com/company/google/). Recommended input to maximize coverage.
3 - 500"waterfall-io"
Full name of the contact. Providing first_name and last_name is preferable when both are available.
4 - 250"John Doe"
First name of the contact.
1 - 100"John"
Last name of the contact.
1 - 100"Doe"
The domain where you want to find contacts. It can be a plain domain or a full URL; Waterfall automatically extracts the company domain.
4 - 500"waterfall.io"
Professional or personal email address.
6 - 254"john.doe@example.com"
Default false. If set to true, Waterfall runs advanced phone enrichment to maximize phone coverage and additional charges may apply when numbers are found.
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. Waterfall includes X-Webhook-Signature containing a compact JWT when webhook signing configuration is available. The JWT protected header contains alg: "EdDSA", kid, and typ: "JWT". Its claims contain iat, exp, jti, job_id, body_hash, and body_hash_alg: "sha-256". body_hash is the unpadded base64url-encoded SHA-256 digest of the exact raw request body bytes. The JSON body is unchanged by signing. Signatures expire exactly 15 minutes after iat; receivers should reject expired signatures. If signing configuration is unavailable or invalid, Waterfall preserves backward compatibility by sending the callback unsigned without X-Webhook-Signature.
2083"https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1"
Optional custom key-value metadata echoed on job input and output (useful for correlating internal source metadata). On create requests, omit the field or send JSON null when no custom fields are needed; both are stored as {}. When present, the value must be a JSON object with keys matching ^[A-Za-z0-9_-]+$ and values that are a string (max 1000 characters), number, or boolean. Empty string, arrays, and other non-object types return HTTP 400. On job GET responses, input.task.custom_fields is always an object ({} or populated).
Response
Contact enrichment job successfully launched.