Company Titles Finder

curl --request GET \
  --url https://api.waterfall.io/v1/company-titles \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.waterfall.io/v1/company-titles"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.waterfall.io/v1/company-titles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.waterfall.io/v1/company-titles",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.waterfall.io/v1/company-titles"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.waterfall.io/v1/company-titles")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.waterfall.io/v1/company-titles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

GET

company-titles

Company Titles Finder

curl --request GET \
  --url https://api.waterfall.io/v1/company-titles \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api.waterfall.io/v1/company-titles"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.waterfall.io/v1/company-titles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.waterfall.io/v1/company-titles",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.waterfall.io/v1/company-titles"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.waterfall.io/v1/company-titles")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.waterfall.io/v1/company-titles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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 returns results synchronously from the launcher. Use this endpoint to re-fetch or audit a previous job, not to poll for completion.

This endpoint is in Beta. Behavior and billing may change. Requires your API key to have Company Titles access enabled.

When to use this

Pass the job_id returned by Company Titles Launcher to retrieve the same job state and title list without re-running the query.

Response fields

Field	Description
`output.titles`	Array of active job titles at the matched company for this page
`output.has_more_pages`	`true` if additional pages exist. Re-run the Launcher with a higher `page_number` to fetch them
`usage`	Per-job cost breakdown, present on completed jobs

Paginating through results

If has_more_pages is true, launch a new job with the same input and increment page_number:

{
  "domain": "stripe.com",
  "page_number": 2
}

Each page returns up to 50,000 titles. The valid range is pages 1 through 100.

Authorizations

x-api-key

string

header

required

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

Query Parameters

job_id

string<uuid>

required

The unique job_id you want to query. This value is returned by the corresponding launcher endpoint.

A UUID.

Example:

"7d44db58-5de3-4e92-a2fb-8325d12c2e8b"

Response

Company Titles job state, input, and any available output.

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
}

Company Titles Launcher

Email Verifier

General guidance

Prospector

Search Contact

Search Company

Contact Enrichment

Phone Enrichment

Company Enrichment

Job Change

Company Reveal

Company Titles

Email Verification

Webhooks

Account

Support

When to use this

Response fields

Paginating through results

Authorizations

Query Parameters

Response

​When to use this

​Response fields

​Paginating through results

Authorizations

Query Parameters

Response

When to use this

Response fields

Paginating through results