Skip to main content
POST
/
v1
/
company-titles
curl --request POST \
  --url https://api.waterfall.io/v1/company-titles \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "domain": "example.com",
  "custom_fields": {},
  "page_number": 1
}
'
{
  "status": "SUCCEEDED",
  "start_date": "2026-02-20T00:00:00+00:00",
  "stop_date": "2026-02-20T00:00:01+00:00",
  "input": {
    "task": {
      "domain": "example.com",
      "company_linkedin": null,
      "custom_fields": {},
      "page_number": 1,
      "job_id": "dae134ce-50e4-4208-b24f-f38687a09377",
      "context_id": "dae134ce-50e4-4208-b24f-f38687a09377"
    }
  },
  "output": {
    "titles": [
      "Software Engineer",
      "VP Sales"
    ],
    "has_more_pages": false,
    "usage": {
      "total_usd": 0.7,
      "balance_remaining_usd": 99.3,
      "persons_count": 0,
      "persons_usd": 0,
      "phones_count": 0,
      "phones_usd": 0,
      "companies_count": 1,
      "companies_usd": 0.7
    }
  }
}
Company Titles OverviewYou input: A company domain or LinkedIn handleYou get: A full list of active job titles currently held at that company, paginated in sets of up to 50,000 titles per page
This endpoint is in Beta. Behavior and billing may change. Requires your API key to have Company Titles access enabled.
Company Titles returns results synchronously. output.titles is included directly in the response. There is no separate polling step.

​
What it’s for

Company Titles returns every distinct job title Waterfall has for a given company. Rather than filtering by title upfront using boolean or keyword logic, you get the full list and apply your own selection criteria downstream: manual review, rule-based filtering, or feeding the titles into an LLM to decide which roles are worth targeting. The best way to use Company Titles is as a first step before running a Search Contact or Prospector job:
  1. Call Company Titles to get the full list of active titles at a company
  2. Review the titles (manually, programmatically, or via an LLM) to identify the ones you care about
  3. Pass those exact titles as a title_list in Search Contact to find only the matching contacts
This is particularly powerful with Search Contact’s title_lists filter, which lets you pass exact title strings rather than relying on keyword or boolean matching. Company Titles gives you the raw material; Search Contact uses it precisely.

​
Pagination

Each page returns up to 50,000 titles. Use page_number to paginate (valid range: 1–100). Check has_more_pages in the response to know whether additional pages exist. 
{
  "domain": "acme.com",
  "page_number": 2
}

​
Example request

{
  "domain": "stripe.com"
}
Or by LinkedIn handle: 
{
  "company_linkedin": "stripe"
}

​
Passing custom metadata

Use custom_fields to attach internal IDs. Echoed back in the response unchanged. 
{
  "domain": "stripe.com",
  "custom_fields": {
    "account_id": "acct_8821"
  }
}

​
Next step

Results are returned directly in the response. To retrieve a past job, use Company Titles 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 Titles request payload.

Request payload for Company Titles. At least one of domain or company_linkedin must be provided.

​
domain
string
required

The domain where you want to find contacts. It can be a plain domain or a full URL; Waterfall automatically extracts the company domain.

Required string length: 2 - 500
Example:

"example.com"

​
company_linkedin
string | null

Company LinkedIn URL or ID/handle (for example google from https://www.linkedin.com/company/google/). Recommended input to maximize coverage.

Maximum string length: 500
Example:

"waterfall-io"

​
custom_fields
object

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"
}
​
page_number
integer<int32>
default:1

Page number for Company Titles results. Each page returns up to 50000 titles. Valid range is 1 through 100.

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

1

Response

Company Titles result returned successfully.

Company Titles 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.771751+00:00"

​
input
object
required
Example:
{
  "task": {
    "domain": "example.com",
    "company_linkedin": null,
    "custom_fields": {},
    "page_number": 1,
    "job_id": "dae134ce-50e4-4208-b24f-f38687a09377",
    "context_id": "dae134ce-50e4-4208-b24f-f38687a09377"
  }
}
​
stop_date
string<date-time>

A date time in ISO 8601 format.

Example:

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

​
output
object

Paginated Company Titles output for a succeeded job.

Example:
{
  "titles": ["Software Engineer", "VP Sales"],
  "has_more_pages": false
}