Company Titles Launcher

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,
  "raw_titles": false
}
'

{
  "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,
      "raw_titles": false,
      "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
    }
  }
}

POST

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,
  "raw_titles": false
}
'

{
  "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,
      "raw_titles": false,
      "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.

Recommended use alongside other endpoints

The best way to use Company Titles is as a first step before running a Search Contact or Prospector job:

Call Company Titles to get the full list of active titles at a company
Review the titles (manually, programmatically, or via an LLM) to identify the ones you care about
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.

Option 1
Option 2

Request payload for Company Titles. At least one of domain or company_linkedin must be provided. When raw_titles is omitted or false, titles are stripped, deduplicated, and ordered ascending by title text. When raw_titles is true, every eligible title is returned exactly as stored, including exact duplicates and whitespace variants, ordered ascending by title text. NULL and whitespace-only titles are excluded in both modes. For stored values "Engineer", "Engineer ", "Engineer", and "Manager", default mode returns ["Engineer", "Manager"]; raw_titles: true returns ["Engineer", "Engineer", "Engineer ", "Manager"].

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

Required string length: 3 - 500

Example:

"waterfall-io"

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

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

raw_titles

boolean

default:false

Return eligible titles with whitespace and duplicates preserved, ordered ascending by title text.

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

Show child attributes

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.

Show child attributes

Example:

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

General guidance

Agent Skills

Prospector

Search Contact

Search Company

Contact Enrichment

Phone Enrichment

Company Enrichment

Job Change

Company Reveal

Company Titles

Email Verification

Webhooks

Account

Support

What it’s for

Recommended use alongside other endpoints

Example request

Passing custom metadata

Next step

Authorizations

Body

Response

​What it’s for

​Recommended use alongside other endpoints

​Pagination

​Example request

​Passing custom metadata

​Next step

Authorizations

Body

Response

What it’s for

Recommended use alongside other endpoints

Pagination

Example request

Passing custom metadata

Next step