Discover account roles

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

Companies describe similar responsibilities in different ways. Retrieve the titles Waterfall has for a company, then choose the ones that fit your persona.

Company Titles is in beta. Your API key must have access enabled. Behavior and billing may change.

{
  "domain": "northstar.example",
  "page_number": 1,
  "custom_fields": {"workspace_id": "ws_208"}
}

Results are synchronous. Read output.titles and check output.has_more_pages. If there are more pages, increment page_number. The supported page range is 1–100, with up to 50,000 titles per page.

From titles to people

Retrieve the titles for the account.
Select relevant titles yourself, with rules, or with your own agent.
Send the selected strings in title_lists to Find relevant people.

Give an agent your product description and target roles, then ask it to select from the returned titles. Keep selection separate from the API request; Company Titles itself does not decide which roles match your product. See Find the buying team for the full workflow. To retrieve an earlier result, use the Company Titles job reference.

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
}

Start here

Use cases

Signups & accounts

Find your buying team

Visitors & existing users

Monitoring

Integration essentials

From titles to people

Authorizations

Body

Response

​From titles to people

Authorizations

Body

Response

From titles to people