Skip to main content
POST
Use Waterfall Company Titles to see which active job titles are available for a company. Start with its domain or LinkedIn identifier, then use the title list to plan a contact search.
This endpoint is in Preview and requires Company Titles access on your API key. API behavior may change, and it is not recommended for critical production workloads.
Results return synchronously in output.titles; no polling is needed. Save input.task.job_id as a fallback if you need to retrieve this result later through Company Titles Finder.
  1. Request the company’s available titles.
  2. Select the roles relevant to your workflow.
  3. Pass those titles in title_lists to Search Contact.
  4. Use Contact Enrichment for selected contacts when you need emails or phone numbers.
The list represents titles in Waterfall’s data. It is not an employee directory or a list of open vacancies.

Example request

You can use company_linkedin instead of domain.

Normalized or raw titles

By default, titles are trimmed, deduplicated, and sorted by title text. Use raw_titles: true to preserve duplicates and whitespace variants. Null and whitespace-only titles are excluded in both modes. For stored titles "Engineer", "Engineer ", "Engineer", and "Manager":

Pagination and usage

Each page returns up to 50,000 titles. If output.has_more_pages is true, repeat the request with the same inputs and increment page_number. Valid page numbers run from 1 to 100. When a company resolves and at least one active title is returned, the lookup is billed at the contracted Company Titles rate. Read output.usage for the job’s cost breakdown.

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