Skip to main content
POST
/
v1
/
search
/
company
Search Company Launcher
curl --request POST \
  --url https://api.waterfall.io/v1/search/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "industries": [
    "software development"
  ],
  "location_countries": [
    "United States"
  ],
  "sizes": [
    "201-500"
  ],
  "page_number": 1,
  "page_size": 20
}
'
{
  "status": "SUCCEEDED",
  "start_date": "2024-01-15T12:00:00.000000+00:00",
  "stop_date": "2024-01-15T12:00:01.843000+00:00",
  "input": {
    "task": {
      "industries": [
        "software development"
      ],
      "location_countries": [
        "United States"
      ],
      "sizes": [
        "201-500"
      ],
      "page_number": 1,
      "page_size": 20,
      "custom_fields": null,
      "job_id": "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e",
      "context_id": "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
    }
  },
  "output": {
    "companies": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "domain": "acme.com",
        "name": "Acme Corp",
        "website": "acme.com",
        "linkedin_id": "acme-corp",
        "description": "Acme Corp builds software solutions for modern sales teams.",
        "logo_url": "https://media.licdn.com/dms/image/acme-corp-logo.png",
        "size": "201-500",
        "employees_count": 350,
        "industry": "Software Development",
        "type": "Privately Held",
        "founded": 2010,
        "address": "100 Market St, San Francisco, California 94105, US",
        "country": "United States",
        "linkedin_url": "https://www.linkedin.com/company/acme-corp/",
        "linkedin_followers": 12500,
        "crunchbase_url": null,
        "funding_details": null
      }
    ]
  }
}
Search Company OverviewYou input: Industry, headquarters country, or headcount range (at least one required)You get: Company profiles with domain, LinkedIn, employee count, industry, HQ location, and funding details
Search Company returns results synchronously — output.companies is included directly in the response. There is no separate polling step.

​
Filters

At least one of the following must be provided:
FieldDescription
industriesLinkedIn industry categories (e.g. software development, information technology and services)
location_countriesCountries where the company is headquartered
sizesLinkedIn employee-size buckets (e.g. 201-500, 501-1000)
All three can be combined — results must match all provided filters.

​
Output

Each company in output.companies includes name, domain, LinkedIn, employee count, industry, founding year, address, and funding details where available.

Authorizations

​
x-api-key
string
header
required

To access the API, provide your API key in x-api-key.

Body

application/json

Search Company request payload with company filters, pagination, and optional custom_fields.

Request payload for Search Company. At least one non-empty list among industries, location_countries, or sizes must be provided.

​
industries
string[]

Industry filters used to match companies.

Maximum array length: 50

Industry filter value for Search Company.

Required string length: 5 - 57
Example:
[
  "software development",
  "information technology and services"
]
​
location_countries
string[]

Country filters used to match companies.

Maximum array length: 50

Country filter value for Search Company.

Required string length: 4 - 40
Example:
["United States", "Canada"]
​
sizes
enum<string>[]

Employee headcount ranges used to filter companies (e.g. 201-500, 501-1000).

Maximum array length: 8

LinkedIn employee-size bucket.

Available options:
1-10,
11-50,
51-200,
201-500,
501-1000,
1001-5000,
5001-10000,
10001+
Example:
["201-500", "501-1000"]
​
page_number
integer<int32>
default:1

Page number for paginated Search Company results.

Required range: 1 <= x <= 100
Example:

1

​
page_size
integer<int32>
default:20

Number of companies to return per page in Search Company.

Required range: 1 <= x <= 250
Example:

20

​
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

Search Company result returned successfully.

Search Company response with job state, 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
Example:
{
  "task": {
    "industries": ["software development"],
    "location_countries": ["United States"],
    "sizes": ["201-500"],
    "page_number": 1,
    "page_size": 20,
    "job_id": "7d44db58-5de3-4e92-a2fb-8325d12c2e8b",
    "context_id": "7d44db58-5de3-4e92-a2fb-8325d12c2e8b"
  }
}
​
stop_date
string<date-time>

A date time in ISO 8601 format.

Example:

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

​
output
object

Search Company output payload.

Example:
{ "companies": [] }