Skip to main content
GET
/
v1
/
enrichment
/
company
Enrichment Company Finder
curl --request GET \
  --url https://api.waterfall.io/v1/enrichment/company \
  --header 'x-api-key: <api-key>'
{
  "status": "SUCCEEDED",
  "start_date": "2024-01-15T12:00:00.000000+00:00",
  "stop_date": "2024-01-15T12:00:14.000000+00:00",
  "input": {
    "task": {
      "linkedin": "acme-corp",
      "domain": null,
      "name": null,
      "webhook_url": null,
      "custom_fields": null,
      "job_id": "0bc82c89-8905-49de-8077-da67f22c3145",
      "context_id": "0bc82c89-8905-49de-8077-da67f22c3145"
    }
  },
  "output": {
    "company": {
      "id": "8563b2e5-4090-49cf-a75b-4bbdedb4956f",
      "domain": "acme.com",
      "name": "Acme Corp",
      "website": "https://www.acme.com/",
      "linkedin_id": "acme-corp",
      "description": "Acme Corp builds enterprise software solutions for mid-market and large companies.",
      "logo_url": "https://media.licdn.com/dms/image/example/company-logo_200_200/logo.png",
      "size": "501-1000",
      "employees_count": 823,
      "industry": "Software Development",
      "type": "Privately Held",
      "founded": 2010,
      "address": null,
      "linkedin_url": "https://www.linkedin.com/company/acme-corp/",
      "linkedin_followers": null,
      "crunchbase_url": null
    }
  }
}
Use the job_id returned by Company 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/company?job_id={job_id}
Use short exponential backoff — most jobs complete in under 15 seconds. Start with a 2s delay, then 4s, then 8s.

​
Job states

StatusMeaning
RUNNINGJob is still processing. Continue polling.
SUCCEEDEDJob is complete. Company data is in output.company.

​
What you get

The output.company object includes:
FieldDescription
nameCompany name
domainPrimary domain
linkedin_id / linkedin_urlLinkedIn slug and full URL
sizeHeadcount range (e.g. 501-1000)
employees_countEstimated headcount
industryIndustry classification
typeOwnership type (e.g. Privately Held)
foundedYear founded
descriptionCompany description from LinkedIn
addressHQ address, if available
logo_urlCompany logo URL

​
Response shape

The input.task object echoes back all fields from the original launch request. Fields not provided will be null.

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

Company enrichment job state, input, and any available output company.

Finder response with company 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.771Z"

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

A date time in ISO 8601 format.

Example:

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

​
output
object