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"
}
'

import requests

url = "https://api.waterfall.io/v1/company-reveal"

payload = { "ip": "8.8.8.8" }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({ip: '8.8.8.8'})
};

fetch('https://api.waterfall.io/v1/company-reveal', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.waterfall.io/v1/company-reveal",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ip' => '8.8.8.8'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.waterfall.io/v1/company-reveal"

	payload := strings.NewReader("{\n  \"ip\": \"8.8.8.8\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.waterfall.io/v1/company-reveal")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ip\": \"8.8.8.8\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.waterfall.io/v1/company-reveal")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ip\": \"8.8.8.8\"\n}"

response = http.request(request)
puts response.read_body

{
  "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": null,
      "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": []
    },
    "usage": {
      "total_usd": 0.07,
      "balance_remaining_usd": 99.93,
      "persons_count": 0,
      "persons_usd": 0,
      "phones_count": 0,
      "phones_usd": 0,
      "companies_count": 1,
      "companies_usd": 0.07
    }
  }
}

POST

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"
}
'

import requests

url = "https://api.waterfall.io/v1/company-reveal"

payload = { "ip": "8.8.8.8" }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({ip: '8.8.8.8'})
};

fetch('https://api.waterfall.io/v1/company-reveal', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.waterfall.io/v1/company-reveal",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'ip' => '8.8.8.8'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.waterfall.io/v1/company-reveal"

	payload := strings.NewReader("{\n  \"ip\": \"8.8.8.8\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.waterfall.io/v1/company-reveal")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ip\": \"8.8.8.8\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.waterfall.io/v1/company-reveal")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ip\": \"8.8.8.8\"\n}"

response = http.request(request)
puts response.read_body

{
  "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": null,
      "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": []
    },
    "usage": {
      "total_usd": 0.07,
      "balance_remaining_usd": 99.93,
      "persons_count": 0,
      "persons_usd": 0,
      "phones_count": 0,
      "phones_usd": 0,
      "companies_count": 1,
      "companies_usd": 0.07
    }
  }
}

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

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.

Value	Meaning
`high`	Strong signal — IP strongly associated with the company
`medium`	Moderate signal — likely match but not definitive
`low`	Weak 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.

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. 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.

Maximum string length: 2083

Example:

"https://example.com/webhook"

custom_fields

object | null

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).

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

Show child attributes

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.

Show child attributes

Job Change Finder

Company Reveal Finder

General guidance

Prospector

Search Contact

Search Company

Contact Enrichment

Phone Enrichment

Company Enrichment

Job Change

Company Reveal

Company Titles

Email Verification

Webhooks

Account

Support

Company Reveal Launcher

How it works

Confidence score

Example request

Passing custom metadata

Next step

Authorizations

Body

Response

​How it works

​Confidence score

​Example request

​Passing custom metadata

​Next step

Authorizations

Body

Response

How it works

Confidence score

Example request

Passing custom metadata

Next step