Skip to main content
GET
/
v1
/
company-titles
Company Titles Finder
curl --request GET \
  --url https://api.waterfall.io/v1/company-titles \
  --header 'x-api-key: <api-key>'
{
  "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

FieldDescription
output.titlesArray of active job titles at the matched company for this page
output.has_more_pagestrue if additional pages exist. Re-run the Launcher with a higher page_number to fetch them
usagePer-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
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
}