Skip to main content
POST
/
v1
/
enrichment
/
company
curl --request POST \ --url https://api.waterfall.io/v1/enrichment/company \ --header 'Content-Type: application/json' \ --header 'x-api-key: <api-key>' \ --data ' { "domain": "acme.com" } '
{ "job_id": "dae884ce-50aa-4208-b24f-f30687a00368", "start_date": "2024-01-15T12:00:00.000000+00:00" }
Company Enrichment OverviewYou input: Domain, LinkedIn URL/slug, or company nameYou get: Headcount, industry, HQ location, company type, description, founded date, and LinkedIn data
This is an asynchronous endpoint. Use the returned job_id with Company 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.

​
Input strategies

PriorityStrategyRequired fieldNotes
1DomaindomainMost reliable. Accepts full URLs too — Waterfall extracts the domain automatically.
2LinkedInlinkedinUse full URL or just the slug (e.g. acme-corp).
3Company namenameLowest accuracy, highest false-positive risk. Use only as a last resort.
Name-only enrichment can match the wrong company. Always prefer domain or linkedin when available.

​
Business notes

Add your internal notes here — pricing tier, credit cost per call, SLA guarantees, data sources used, etc.

​
Next step

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

Company enrichment payload: provide one company identifier (domain, linkedin, or name) plus optional webhook_url and custom_fields.

Request payload to launch a company enrichment job.

​
domain
string
required

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"

​
linkedin
string | null

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"

​
name
string

The name of the company where you want to find contacts.

Required string length: 1 - 500
Example:

"Waterfall"

​
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

Company enrichment job successfully launched.

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