Company Reveal Finder

curl --request GET \
  --url https://api.waterfall.io/v1/company-reveal \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}

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::Get.new(url)
request["x-api-key"] = '<api-key>'

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

GET

company-reveal

Company Reveal Finder

curl --request GET \
  --url https://api.waterfall.io/v1/company-reveal \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}

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::Get.new(url)
request["x-api-key"] = '<api-key>'

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

Use the job_id from Company Reveal Launcher to retrieve a stored result. The launcher already returns the result synchronously, so this endpoint is useful when you need to look up that result again.

Read the result

Read the job status, then inspect output.type, output.confidence_score, and output.company. A completed job does not mean a company was identified: the company object can be empty. See Company Reveal Launcher for the output categories and interpretation. Retrieving a stored job does not run a fresh IP lookup.

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 Reveal job state and output 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

Get started

Integration guides

Prospector

Search Contact

Search Company

Contact Enrichment

Phone Enrichment

Company Enrichment

Job Change

Company Reveal

Company Titles

Email Verification

Webhooks

Account

Specification

Read the result

Authorizations

Query Parameters

Response

​Read the result

Authorizations

Query Parameters

Response

Read the result