Skip to main content
POST
/
v1
/
company-reveal
Company Reveal Launcher
curl --request POST \
  --url https://api.waterfall.io/v1/company-reveal \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "ip": "8.8.8.8"
}
'
{
  "status": "SUCCEEDED",
  "start_date": "2026-03-07T10:00:00.000000+00:00",
  "stop_date": "2026-03-07T10:00:00.300000+00:00",
  "input": {
    "task": {
      "ip": "8.8.8.8",
      "webhook_url": null,
      "custom_fields": {},
      "job_id": "b7e4648f-4f15-4f2f-9d09-7af635ce6c24",
      "context_id": "b7e4648f-4f15-4f2f-9d09-7af635ce6c24"
    }
  },
  "output": {
    "ip": "8.8.8.8",
    "type": "company",
    "confidence_score": "high",
    "ip_geo": {
      "city": "San Francisco",
      "state": "California",
      "country": "United States"
    },
    "company": {
      "id": "54fa90d8-7ba7-4b6d-b5ec-82ee3e184166",
      "domain": "stripe.com",
      "name": "Stripe",
      "website": "stripe.com",
      "linkedin_id": "stripe",
      "description": "Stripe is a financial infrastructure platform for businesses.",
      "logo_url": "https://logo.clearbit.com/stripe.com",
      "size": "5001-10000",
      "employees_count": 8000,
      "industry": "Financial Services",
      "type": "Privately Held",
      "founded": 2010,
      "address": "354 Oyster Point Blvd, South San Francisco, California 94080, US",
      "country": "United States",
      "linkedin_url": "https://www.linkedin.com/company/stripe/",
      "linkedin_followers": 1500000,
      "crunchbase_url": "https://www.crunchbase.com/organization/stripe",
      "funding_details": {
        "total_funding_rounds": 0,
        "total_funding_usd": 0,
        "funding_rounds": []
      },
      "recent_job_posting_count": 0,
      "technologies": []
    }
  }
}
Company Reveal OverviewYou input: An IPv4 addressYou get: Company identity (domain, name, LinkedIn, industry, headcount) plus IP geolocation (city, state, country) and a confidence score
This endpoint is in Beta — not recommended for critical production workloads. API behavior may change.

​
How it works

Unlike other Waterfall async endpoints, Company Reveal returns the result immediately in the response body — no polling required. The job is also persisted, so you can retrieve it later using the Company Reveal Finder with the returned job_id.

​
Confidence score

The confidence_score field indicates how certain Waterfall is that the IP belongs to the identified company.
ValueMeaning
highStrong signal — IP strongly associated with the company
mediumModerate signal — likely match but not definitive
lowWeak signal — treat result with caution

​
Example request

{
  "ip": "8.8.8.8"
}

​
Passing custom metadata

Use custom_fields to attach internal IDs or labels — echoed back in the response unchanged. 
{
  "ip": "8.8.8.8",
  "custom_fields": {
    "session_id": "abc123",
    "source": "inbound-web"
  }
}

​
Next step

The result is returned directly in the response. To retrieve a past job, use Company Reveal Finder with the 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 Reveal request payload.

Request payload for Company Reveal.

​
ip
string<ipv4>
required
Example:

"8.8.8.8"

​
webhook_url
string<uri> | null

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://example.com/webhook"

​
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 Reveal result returned successfully.

Company Reveal response with synchronous job envelope and 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.771751+00:00"

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

A date time in ISO 8601 format.

Example:

"2025-02-05T15:46:35.771751+00:00"

​
output
object

Company Reveal output payload.