openapi: "3.1.0"
info:
title: Waterfall
version: 1.7.0
description: >-
Waterfall API provides a broad set of capabilities in V1. Most endpoints are asynchronous: you start a job (POST) and then retrieve results (GET). Some endpoints return immediate responses. Webhooks are also available to simplify asynchronous integrations. Below is an overview of the available endpoints:
#### 1\. Prospector
Find contacts at target accounts using filters like job titles and location. Get contact details such as titles, real-time verified emails, social profiles, and phone numbers.
- **Prospector Launcher:** Start a contact search using a domain name, LinkedIn profile, or company name. Returns a `job_id`.
- **Prospector Finder:** Retrieve results using the `job_id` from the Prospector Launcher.
#### 2\. Contact Enrichment
Enrich contact information by inputting professional/personal emails, LinkedIn URL/slug, or name + domain. Get enriched data like verified emails, job titles, and locations.
- **Contact Enrichment Launcher**: Start a contact enrichment process. Returns a `job_id`.
- **Contact Enrichment Finder**: Retrieve results using the `job_id` from the Contact Enrichment Launcher.
#### 3\. Company Enrichment
Enrich company data by inputting a domain, LinkedIn URL/slug, or company name. Receive details like headcount, industry, and headquarters.
- **Company Enrichment Launcher**: Start a company search using a domain name, LinkedIn URL/slug, or company name. Returns a `job_id`.
- **Company Enrichment Finder**: Retrieve results using the `job_id` from the Company Enrichment Launcher.
#### 4\. Phone Number Enrichment
Get mobile numbers by inputting an email, LinkedIn URL/slug, or name + domain.
- **Phone Enrichment Launcher**: Start a phone number enrichment process. Returns a `job_id`.
- **Phone Enrichment Finder**: Retrieve results using the `job_id` from the Phone Enrichment Launcher.
#### 5\. Search Contact
Search contacts using either a specific contact LinkedIn, a specific company, or company-set filters, with optional title, seniority, department, location, and hiring-date constraints.
- **Search Contact Launcher**: Start a search contact job and get the result payload.
- **Search Contact Finder**: Retrieve search contact job state and output by `job_id`.
#### 6\. Search Company
Search companies by industry, country, and company size filters with pagination support.
- **Search Company Launcher**: Start a search company job and get the result payload.
- **Search Company Finder**: Retrieve search company job state and output by `job_id`.
#### 7\. Job Change
Detect whether a contact has changed jobs using company and/or contact identifiers.
- **Job Change Launcher**: Start a job change check and get the result payload.
- **Job Change Finder**: Retrieve job change job state and output by `job_id`.
#### 8\. Company Reveal
Reveal company information from an IPv4 address and retrieve persisted reveal jobs by `job_id`.
- **Company Reveal Launcher**: Submit an IPv4 and get the reveal job envelope immediately.
- **Company Reveal Finder**: Retrieve a persisted company reveal job state and output by `job_id`.
#### 9\. Email Verification
Verify emails with high accuracy, reducing bounce rates. This endpoint works asynchronously, providing results in a single API call. You can start an email verification process and get the verification status of a given email.
#### 10\. Account Reporter
Provides information about your account's usage.
#### 11\. API Keys Management
Use a single master key to manage all your API keys: create new keys, activate/deactivate them, and view all your keys in one place. See [API Keys Management](https://docs.waterfall.io/v1/api-keys-overview).
---
# Versioning
Waterfall API versioning follows Semantic Versioning (`MAJOR.MINOR.PATCH`):
- **Patch** (`1.1.x`): Non-breaking revisions and fixes only. No existing contract changes.
- **Minor** (`1.x.0`, for example `1.2.0`): Backward-compatible additions. Adding new services/endpoints uses a minor version increase when existing services are unchanged.
- **Major** (`x.0.0`, for example `2.0.0`): Breaking changes to existing contracts/behavior and major platform overhauls.
## Endpoint Lifecycle Stages
Waterfall uses modern launch stages aligned with Google Cloud terminology:
- **Preview**
- Meaning: Early public version available for testing and feedback (equivalent to older Alpha/Beta phases).
- Production use: Not recommended for critical production workloads.
- SLA: No.
- Stability: API behavior may change.
- **GA (General Availability)**
- Meaning: Fully released and production-ready service or API.
- Production use: Yes.
- SLA: Yes.
- Stability: Backward compatibility is guaranteed within the version.
- **Deprecated**
- Meaning: Feature or API is scheduled for retirement and a newer alternative exists.
- Production use: Should migrate away.
- SLA: Limited.
- Stability: No new features; removal date announced.
- **Decommissioned / End of Life**
- Meaning: Feature or API has been shut down and is no longer available.
- Production use: No.
- SLA: No.
- Stability: Endpoint disabled or removed.
Current mapping in this API spec: all endpoints are `GA` except `/v1/company-reveal`, `/v1/search/company`, `/v1/job/change`, and `/v1/company-titles`, which are `Preview`.
---
# Authentication
To access the API, you need the API key provided in your contract. You can ask for multiple API keys for different teams' usage.
All API request URLs start with [https://api.waterfall.io/v1/](https://api.waterfall.io/v1/). Provide your API key in the `x-api-key` header.
---
# Rate limit
The Prospector, Search, Enrichment, Job Change and Verify Email APIs allow a maximum of 50 requests per minute (60 seconds). Should you encounter rate limit errors or anticipate a need for increased capacity, please reach out to your account manager for assistance. There are no rate limits for the Account Reporter API.
##### X-RateLimit-Limit
The maximum number of requests you can make per interval. Only sent when the rate limit is reached.
##### X-RateLimit-Interval
The length of the interval in seconds. Only sent when the rate limit is reached.
##### Retry-After
The number of seconds to wait until the rate limit window resets. Only sent when the rate limit is reached.
---
# Filters
Waterfall offers three filtering options for prospect requests:
## 1. Title Filter
The `title_filter` parameter allows requesting specific titles with each request.
- If `title_filter` is present, it must not be empty.
- If `title_filter` is present and not empty (for example `"title_filter": "((accountant) OR (accounting)) AND NOT (intern)"`), Waterfall will use that filter.
- If `title_filter` is not present, Waterfall will try [title_filters](https://docs.waterfall.io/v1/prospector-multiple-title-filters).
- At least one of `title_filter` or `title_filters` must be provided.
The filter can be any Boolean expression. Accepted operators are `AND`, `OR`, and `NOT`. Operators must be uppercase and separated by spaces.
There is no need to enclose multi-word titles in parentheses.
Matching for each title is inclusive. For example:
- `manager` will match `program manager`, `senior manager` and `account manager sales`
- `vp data` will match `vp innovation, data science, co-founder`, `vp information and data` and `vp data science`
- `head product` will match `global head of product` and `head of product management office`
- `data lead` will match `lead data scientist`, `data lead engineer`, `data lead` and `data engineering lead`
A few valid filter examples:
- manager
- manager AND NOT project manager
- manager AND NOT (project manager OR sales manager)
- ( (manager OR director) AND (sales OR marketing) ) AND NOT ( project manager OR sales manager)
- (accountant OR accounting) AND NOT intern
- ( (ceo) OR (c.e.o) OR (co-ceo) OR (coceo) OR (chief executive officer) OR (founder) OR (co-founder) OR (cofounder) OR (owner) OR (co-owner) OR (coowner) OR (cmo) OR (c.m.o) OR (chief marketing officer) OR (cco) OR (c.c.o) OR (chief commercial officer) OR (chief e-commerce officer) OR (chief ecommerce officer) ) OR ( ( (chief) OR (cheffe) OR (director) OR (vp) OR (svp) OR (vice) OR (president) OR (vicepresident) OR (executive) OR (head) ) AND ( (marketing) OR (growth) OR (e-commerce) OR (ecommerce) ) AND NOT ( (assistant) OR (analyst) OR (intern) OR (apprenticeship) OR (sales) OR (finance) OR (recruitment) OR (project manager) OR (hr) OR (human resources) OR (talent) OR (design) OR (logistic) OR (warehouse) OR (engineer) OR (developer) OR (student) OR (merchandising) OR (digital) OR (brand) OR (trade) OR (influencer) OR (export) OR (wholesale) OR (whole sale) OR (information) OR (specialist) ) )
A few invalid filter examples:
- `mangerANDdirector`: spaces must be used around operators
- `manager NOT (project manager)`: invalid boolean expression
- `(accountant OR accounting AND NOT intern`: missing closing parenthesis before AND
We recommend using parentheses to make sure operator precedence is what you intend.
For example filter `(CFO) OR (Cofounder) AND NOT ((Vice) OR (Assistant) OR (Executive Assistant))` will match title `Assistant CFO.` The Boolean expression is `True OR False AND NOT True` and is evaluated as `True OR False AND NOT True = True OR False AND False = True OR False = True`
In this case, the intended filter is `((CFO) OR (Cofounder)) AND NOT ((Vice) OR (Assistant) OR (Executive Assistant))`. Note the extra parenthesis around the first part.
If you need help with writing title filters, contact your account manager to schedule a call with the support team.
---
## 2. Multiple Title Filters
The `title_filters` parameter allows requesting multiple title filters in a specific order. It is used when [title_filter](https://docs.waterfall.io/v1/prospector-title-filter) is not present.
Example:
``` json
"title_filters": [
{
"name": "ceo level",
"filter": "ceo OR founder OR owner"
},
{
"name": "sales",
"filter": "revenue OR growth OR sales"
},
{
"name": "marketing or operations",
"filter": "marketing OR operations"
}
]
```
Waterfall will try each filter in the order provided up to the requested `limit`.
You can provide up to 5 `title_filters` entries per request.
---
## 3. Location Filter
The location-based search is performed with `location_name`, `location_country`, and `location_countries`.
#### location_country
The `location_country` parameter represents the country of the contact's current address. Use full country names such as `United States` or `France`. Partial values such as `United` or `Saudi` should be avoided. The country list is available [here](https://waterfall-io-public.s3.amazonaws.com/waterfall_location_country.txt).
Empty values are ignored.
#### location_countries
The `location_countries` parameter is a list of countries where the contact's current address can be. If it is present and non-empty, it is used instead of `location_country`.
- \["France"\]
- \["France", "Germany"\]
You can provide up to 50 countries. The full list is available [here](https://waterfall-io-public.s3.us-east-1.amazonaws.com/waterfall_location_country.txt).
#### location_name
The `location_name` parameter represents the location of the contact's current address. Typical locations are:
- `San Francisco, California, United States`
- `Paris, Ile-De-France, France`
A location can include city, region/state, and country. Partial matches are possible. Common partial formats are:
- city, region: `San Francisco, California`, `Paris, Ile-De-France`
- region, country: `California, United States`, `Ile-De-France, France`
- city: `San Francisco`, `Paris`
- region: `California`, `Ile-De-France`
- country:`United States`, `France`
In many cases, the best results are obtained using only the region.
Empty values are ignored.
---
# Errors
The waterfall API uses conventional HTTP response codes to indicate the success or failure of a request, with detailed information in case of error.
Error payload structure:
- `category` is the high-level classification (`AUTH`, `VALIDATION`, `NOT_FOUND`, etc.).
- `code` is the stable machine-readable identifier for a specific failure case.
- Every `code` is namespaced by category using the format `CATEGORY_DETAIL` (for example `VALIDATION_BAD_REQUEST`).
- The `category` field must always match the prefix of the `code` field.
- Use `category` for broad handling (retry/auth/permissions) and `code` for precise logic and analytics.
| Status Code | Description |
| --- | --- |
| 200 OK | The request was successful. |
| 400 Bad Request | Your request was not valid. |
| 401 Unauthorized | Missing API key. |
| 403 Forbidden | Bad API key. |
| 404 Not Found | The requested endpoint does not exist. |
| 500 Internal Server Error | Something went wrong on our end. |
---
# Contact Support
Contact Support:
Email: [felix@waterfall.io](https://mailto:felix@waterfall.io)
termsOfService: https://www.waterfall.io/#FAQs
contact:
email: felix@waterfall.io
components:
securitySchemes:
api_key:
description: To access the API, provide your API key in `x-api-key`.
type: apiKey
in: header
name: x-api-key
parameters:
JobIdQueryParameter:
name: job_id
description: >
The unique job_id you want to query. This value is returned by the corresponding launcher endpoint.
example: dae134ce-50e4-4208-b24f-f38687a09377
in: query
required: true
schema:
$ref: '#/components/schemas/UUIDString'
MonthQueryParameter:
name: month
in: query
required: false
description: >
Optional month in `YYYY-MM` format used to scope usage counters. Mutually
exclusive with `start_date` and `end_date`. The month's start must not be
more than 12 months in the past, and must not be entirely in the future.
example: "2025-01"
schema:
type: string
pattern: '^\d{4}-\d{2}$'
minLength: 7
maxLength: 7
StartDateQueryParameter:
name: start_date
in: query
required: false
description: >
Optional interval start date in `YYYY-MM-DD` format, UTC, inclusive. Must
be provided together with `end_date`, and is mutually exclusive with
`month`. Must not be more than 12 months before the current UTC date, and
must not be entirely in the future (at least one day of the interval must
be today or earlier).
example: "2025-01-01"
schema:
type: string
format: date
pattern: '^\d{4}-\d{2}-\d{2}$'
minLength: 10
maxLength: 10
EndDateQueryParameter:
name: end_date
in: query
required: false
description: >
Optional interval end date in `YYYY-MM-DD` format, UTC, exclusive. Must
be provided together with `start_date`, must be strictly after
`start_date`, and the interval cannot exceed 12 months. Mutually
exclusive with `month`.
example: "2025-02-01"
schema:
type: string
format: date
pattern: '^\d{4}-\d{2}-\d{2}$'
minLength: 10
maxLength: 10
schemas:
WebhookJwksResponse:
type: object
additionalProperties: false
description: Public JSON Web Key Set used to verify Waterfall webhook signatures.
required:
- keys
properties:
keys:
type: array
minItems: 1
example:
- kty: OKP
crv: Ed25519
kid: webhook-key-2026-06
use: sig
alg: EdDSA
x: Q7HQWfd9_2hmzNwwBqqJ2l7CkDFv3cAvQ44asbkD-MA
items:
$ref: "#/components/schemas/WebhookEd25519Jwk"
example:
keys:
- kty: OKP
crv: Ed25519
kid: webhook-key-2026-06
use: sig
alg: EdDSA
x: Q7HQWfd9_2hmzNwwBqqJ2l7CkDFv3cAvQ44asbkD-MA
WebhookEd25519Jwk:
type: object
additionalProperties: false
description: Ed25519 public verification key represented as an OKP JWK.
required:
- kty
- crv
- kid
- use
- alg
- x
properties:
kty:
type: string
enum:
- OKP
crv:
type: string
enum:
- Ed25519
kid:
type: string
minLength: 1
maxLength: 200
description: Key identifier used to select the verification key.
use:
type: string
enum:
- sig
alg:
type: string
enum:
- EdDSA
x:
type: string
minLength: 43
maxLength: 43
description: Base64url-encoded Ed25519 public key bytes without padding.
DomainString:
type: string
minLength: 4
maxLength: 500
description: >
The domain where you want to find contacts. It can be a plain domain or
a full URL; Waterfall automatically extracts the company domain.
examples:
- waterfall.io
CompanyNameString:
type: string
minLength: 3
maxLength: 500
description: The name of the company where you want to find contacts.
examples:
- Waterfall
LinkedInString:
type:
- string
- "null"
minLength: 3
maxLength: 500
description: >
Company LinkedIn URL or ID/handle (for example `google` from
`https://www.linkedin.com/company/google/`). Recommended input to
maximize coverage.
examples:
- waterfall-io
FirstNameString:
type:
- string
- "null"
minLength: 1
maxLength: 100
description: First name of the contact.
examples:
- John
LastNameString:
type:
- string
- "null"
minLength: 1
maxLength: 100
description: Last name of the contact.
examples:
- Doe
FullNameString:
type:
- string
- "null"
minLength: 4
maxLength: 250
description: >
Full name of the contact. Providing `first_name` and `last_name` is
preferable when both are available.
examples:
- John Doe
TitleFilterString:
type:
- string
- "null"
minLength: 2
maxLength: 10000
description: >
Boolean title filter expression used to target specific roles. Supported
operators are uppercase `AND`, `OR`, and `NOT`.
examples:
- ( (manager OR director) AND (sales OR marketing) ) AND NOT ( project manager OR sales manager)
externalDocs:
url: https://docs.waterfall.io/v1/prospector-title-filter
TitleFilterNullableString:
type:
- string
- "null"
minLength: 2
maxLength: 10000
description: >
Single title filter expression. One of `title_filter` or
`title_filters` is required.
examples:
- ( (manager OR director) AND (sales OR marketing) ) AND NOT ( project manager OR sales manager)
externalDocs:
url: https://docs.waterfall.io/v1/prospector-title-filter
TitleFilterNameString:
type:
- string
- "null"
minLength: 2
maxLength: 500
description: Name portion of the title filter.
examples:
- founders and c level
TitleFilterRequest:
description: Title filter request
type: object
properties:
name:
$ref: '#/components/schemas/TitleFilterNameString'
filter:
$ref: '#/components/schemas/TitleFilterString'
required:
- name
- filter
TitleListTitleString:
type: string
minLength: 2
maxLength: 500
description: A title value used in `title_lists`.
examples:
- software engineer
TitleListRequest:
type: object
description: Title list request.
properties:
name:
$ref: '#/components/schemas/TitleFilterNameString'
titles:
type: array
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/TitleListTitleString'
examples:
- - software engineer
- product manager
required:
- name
- titles
WebHookURLString:
type: string
format: uri
maxLength: 2083
description: >
Optional webhook callback URL. If supplied, Waterfall POSTs the same
payload returned by the Finder endpoint when processing completes. If
your webhook responds with `429`, `500`, `502`, or `504`, Waterfall
retries delivery up to 5 times with exponential backoff. Waterfall
includes `X-Webhook-Signature` containing a compact JWT when webhook
signing configuration is available. The JWT protected header contains
`alg: "EdDSA"`, `kid`, and `typ: "JWT"`. Its claims contain `iat`,
`exp`, `jti`, `job_id`, `body_hash`, and `body_hash_alg: "sha-256"`.
`body_hash` is the unpadded base64url-encoded SHA-256 digest of the
exact raw request body bytes. The JSON body is unchanged by signing.
Signatures expire exactly 15 minutes after `iat`; receivers should
reject expired signatures. If signing configuration is unavailable or
invalid, Waterfall preserves backward compatibility by sending the
callback unsigned without `X-Webhook-Signature`.
examples:
- https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1
CustomFieldsObject:
type:
- object
- "null"
maxProperties: 100
patternProperties:
'^[A-Za-z0-9_-]+$':
oneOf:
- type: string
maxLength: 1000
- type: number
- type: boolean
additionalProperties: false
description: >
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).
examples:
- tenantId: 0e9d26b7-cdb5-4d95-b248-59ac389d2e8a
workflowId: ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4
waterfallRequestId: 1b49c542-f47a-406b-a95f-a1859d1461af
LimitInteger:
type:
- integer
- "null"
format: int32
minimum: 1
maximum: 500
default: 10
description: Maximum number of contacts returned per company for a search.
examples:
- 3
SearchContactPageNumberInteger:
type: integer
format: int32
minimum: 1
maximum: 100
default: 1
description: Page number for paginated Search Contact results.
examples:
- 1
SearchContactPageSizeInteger:
type: integer
format: int32
minimum: 1
maximum: 250
default: 10
description: Number of contacts to return per page in Search Contact.
examples:
- 10
SearchCompanyPageNumberInteger:
type: integer
format: int32
minimum: 1
maximum: 100
default: 1
description: Page number for paginated Search Company results.
examples:
- 1
SearchCompanyPageSizeInteger:
type: integer
format: int32
minimum: 1
maximum: 250
default: 20
description: Number of companies to return per page in Search Company.
examples:
- 20
CompanyTitlesPageNumberInteger:
type: integer
format: int32
minimum: 1
maximum: 100
default: 1
description: >
Page number for Company Titles results. Each page returns up to 50000 titles.
Valid range is 1 through 100.
examples:
- 1
SearchCompanyIndustryString:
type: string
minLength: 5
maxLength: 57
description: >
LinkedIn industry filter value. Use title-case industry names from the
supported industry list:
https://waterfall-io-public.s3.us-east-1.amazonaws.com/industries.txt.
examples:
- Software Development
externalDocs:
description: Full list of supported LinkedIn industries.
url: https://waterfall-io-public.s3.us-east-1.amazonaws.com/industries.txt
SearchCompanyCountryString:
type: string
minLength: 4
maxLength: 40
description: Country filter value for Search Company.
examples:
- United States
SearchContactEmployeeRangeString:
type: string
description: LinkedIn employee-size bucket.
enum:
- "1-10"
- "11-50"
- "51-200"
- "201-500"
- "501-1000"
- "1001-5000"
- "5001-10000"
- "10001+"
examples:
- "201-500"
SeniorityString:
type: string
minLength: 3
maxLength: 14
description: Contact seniority returned on person payloads.
enum:
- Owner
- CXO
- Partner
- Vice President
- Director
- Manager
- Senior
- Entry
- Other
examples:
- Manager
DepartmentString:
type: string
minLength: 5
maxLength: 22
description: Contact department returned on person payloads.
enum:
- Leadership
- Engineering
- Product Management
- Sales
- Marketing
- Customer Success
- Finance
- Accounting
- Legal
- Human Resources
- Information Technology
- Operations
- Education
- Other
examples:
- Engineering
IncludePhonesBoolean:
type: boolean
default: false
description: >
Default `false`. If set to `true`, Waterfall runs advanced phone
enrichment to maximize phone coverage and additional charges may apply
when numbers are found.
LocationNameString:
type: string
minLength: 1
maxLength: 200
description: >
Location of the contact's current address. Supports city/region/country
and partial forms (for example, region only).
examples:
- San Francisco, California, United States
externalDocs:
url: https://docs.waterfall.io/v1/prospector-location-filter
LocationCountryString:
type:
- string
- "null"
minLength: 1
maxLength: 200
description: >
Country of the contact's current address. Use full country names (for
example, `United States` or `France`).
examples:
- United States
externalDocs:
url: https://docs.waterfall.io/v1/prospector-location-filter
DataTimeString:
type: string
format: date-time
description: A date time in ISO 8601 format.
examples:
- "2025-02-05T15:46:35.771751+00:00"
UUIDString:
type: string
format: uuid
description: A UUID.
examples:
- 7d44db58-5de3-4e92-a2fb-8325d12c2e8b
APIKeyNoteString:
type: string
minLength: 1
maxLength: 250
description: Notes associated with the API key.
examples:
- My API key
EmailString:
type: string
format: email
minLength: 6
maxLength: 254
description: Professional or personal email address.
examples:
- john.doe@example.com
JobStatusEnum:
type: string
enum:
- RUNNING
- SUCCEEDED
- FAILED
- TIMED_OUT
- ABORTED
description: The status of the job.
examples:
- RUNNING
EmailConfidenceEnum:
type: string
description: Confidence level assigned to a verified professional email.
enum:
- high
- low
EmailStatusEnum:
type: string
description: Verification status used for person-level professional emails.
enum:
- invalid
- risky
- safe
- unknown
- provider_error
EmailVerifyStatusEnum:
type: string
description: Verification status returned by the Verify Email endpoint.
enum:
- valid
- invalid
- risky
- unknown
EmailOutput:
type: object
description: Verified email details returned by the Verify Email endpoint.
properties:
email:
type:
- string
- "null"
format: email
maxLength: 254
examples:
- "emre@waterfall.io"
domain:
$ref: '#/components/schemas/DomainString'
email_status:
$ref: '#/components/schemas/EmailVerifyStatusEnum'
smtp_provider:
type: string
examples:
- "Google"
mx_records:
type: array
items:
type: string
examples:
- - "aspmx.l.google.com"
- "alt1.aspmx.l.google.com"
- "alt2.aspmx.l.google.com"
- "aspmx3.googlemail.com"
- "aspmx2.googlemail.com"
FundingRound:
type: object
description: A single funding round record for a company.
properties:
round_name:
type: string
examples:
- "Series F"
round_date:
type: string
format: date
examples:
- "2024-04-22"
investor_count:
type: integer
format: int32
examples:
- 5
amount_raised_usd:
type: integer
format: int64
examples:
- 200000000
investor_names:
type: array
items:
type: string
examples:
- - "Bossa Invest"
- "Coatue"
- "Dragoneer Investment Group"
- "Founders Fund"
- "Greenoaks"
FundingDetails:
type: object
description: Aggregated funding information and funding round history for a company.
properties:
total_funding_rounds:
type: integer
format: int32
examples:
- 9
total_funding_usd:
type: integer
format: int64
examples:
- 1995000000
funding_rounds:
type: array
items:
$ref: '#/components/schemas/FundingRound'
Company:
type: object
description: Company profile returned in prospector results.
properties:
id:
$ref: '#/components/schemas/UUIDString'
domain:
$ref: '#/components/schemas/DomainString'
company_name:
$ref: '#/components/schemas/CompanyNameString'
website:
$ref: '#/components/schemas/DomainString'
linkedin_id:
type: string
examples:
- "deel"
linkedin_url:
type: string
format: uri
examples:
- "https://www.linkedin.com/company/deel/"
linkedin_description:
type: string
linkedin_logo_url:
type:
- string
- "null"
format: uri
size:
type:
- string
- "null"
linkedin_size:
type:
- string
- "null"
linkedin_industry:
type:
- string
- "null"
linkedin_type:
type:
- string
- "null"
linkedin_followers:
type:
- integer
- "null"
format: int32
linkedin_founded:
type:
- integer
- "null"
format: int32
examples:
- 2019
linkedin_employees_count:
type: integer
format: int32
linkedin_address:
type:
- string
- "null"
examples:
- "San Francisco, California, United States"
country:
$ref: '#/components/schemas/LocationCountryString'
generic_emails:
type: array
description: Generic company email addresses (for example, info@ or sales@). Empty list when none are known.
items:
type: string
format: email
examples:
- - "info@abc.com"
- "sales@abc.com"
CompanyEnriched:
type: object
description: Enriched company profile returned by company enrichment finder.
properties:
id:
$ref: '#/components/schemas/UUIDString'
domain:
$ref: '#/components/schemas/DomainString'
name:
$ref: '#/components/schemas/CompanyNameString'
website:
$ref: '#/components/schemas/DomainString'
linkedin_id:
type:
- string
- "null"
examples:
- "rippling"
description:
type:
- string
- "null"
examples:
- "Rippling is a workforce management system that eliminates the friction from running a business..."
logo_url:
type:
- string
- "null"
format: uri
examples:
- "https://media.licdn.com/dms/image/v2/C560BAQGTg3igNET25Q/company-logo_200_200/company-logo_200_200/0/1654722845874/rippling_logo?e=2147483647&v=beta&t=qq8RLQly9P0IXbPKjbcNiSdbT8g18dJhEZ1apYPIHd0"
size:
type: string
examples:
- "1001-5000"
employees_count:
type:
- integer
- "null"
format: int32
examples:
- 3854
industry:
type:
- string
- "null"
examples:
- "Software Development"
type:
type:
- string
- "null"
examples:
- "Privately Held"
founded:
type:
- integer
- "null"
format: int32
examples:
- 2016
address:
type: string
examples:
- "430 California St; San Francisco, California 94104, US"
country:
$ref: '#/components/schemas/LocationCountryString'
linkedin_url:
type:
- string
- "null"
format: uri
examples:
- "https://www.linkedin.com/company/rippling/"
linkedin_followers:
type:
- integer
- "null"
format: int32
examples:
- 186401
crunchbase_url:
type:
- string
- "null"
format: uri
examples:
- "https://www.crunchbase.com/organization/rippling"
funding_details:
$ref: '#/components/schemas/FundingDetails'
recent_job_posting_count:
type:
- integer
- "null"
format: int32
examples:
- 12
technologies:
type: array
items:
type: string
examples:
- - "AWS"
- "Snowflake"
- "Salesforce"
Experience:
type: object
description: Employment experience entry for a person.
properties:
title:
type: string
location:
type:
- string
- "null"
company_name:
$ref: '#/components/schemas/CompanyNameString'
company_linkedin_id:
type: string
company_linkedin_url:
type:
- string
- "null"
format: uri
company_domain:
$ref: '#/components/schemas/DomainString'
start_year:
type:
- integer
- "null"
format: int32
start_month:
type:
- integer
- "null"
format: int32
start_date:
type:
- string
- "null"
format: date
end_year:
type:
- integer
- "null"
format: int32
end_month:
type:
- integer
- "null"
format: int32
end_date:
type:
- string
- "null"
format: date
is_current:
type:
- boolean
- "null"
description:
type: string
Person:
type: object
description: Person profile returned by prospecting and contact/phone enrichment workflows.
properties:
id:
$ref: '#/components/schemas/UUIDString'
first_name:
type:
- string
- "null"
examples:
- "John"
last_name:
type: string
examples:
- "DoeAlcaraz"
linkedin_id:
type: string
examples:
- "johndoe"
linkedin_url:
type: string
format: uri
examples:
- "https://www.linkedin.com/in/johndoe/"
about:
type:
- string
- "null"
personal_email:
type:
- string
- "null"
format: email
location:
type:
- string
- "null"
examples:
- "Los Angeles, California, United States"
country:
$ref: '#/components/schemas/LocationCountryString'
company_id:
$ref: '#/components/schemas/UUIDString'
company_linkedin_id:
type: string
examples:
- "acmd"
company_name:
type: string
examples:
- "ACME"
company_domain:
type: string
examples:
- "acme.com"
professional_email:
type: string
format: email
examples:
- "john.doe@acme.com"
mobile_phone:
type:
- string
- "null"
phone_numbers:
type:
- array
- "null"
items:
type: string
title:
type: string
examples:
- "Lifecycle Marketing Specialist"
seniority:
$ref: '#/components/schemas/SeniorityString'
department:
$ref: '#/components/schemas/DepartmentString'
experiences:
type: array
items:
$ref: '#/components/schemas/Experience'
email_verified:
type: boolean
email_confidence:
$ref: '#/components/schemas/EmailConfidenceEnum'
email_verified_status:
$ref: '#/components/schemas/EmailStatusEnum'
domain_age_days:
type: string
smtp_provider:
type:
- string
- "null"
examples:
- "Google"
mx_record:
type:
- string
- "null"
examples:
- "aspmx.l.google.com"
ProspectCreateRequest:
allOf:
- type: object
required:
- domain
properties:
domain:
$ref: '#/components/schemas/DomainString'
- type: object
anyOf:
- type: object
required: [ title_filter ]
properties:
title_filter:
$ref: '#/components/schemas/TitleFilterNullableString'
- type: object
required: [ title_filters ]
properties:
title_filters:
type:
- array
- "null"
items:
$ref: '#/components/schemas/TitleFilterRequest'
minItems: 1
maxItems: 5
type: object
description: Request payload to launch a prospector job.
properties:
domain:
$ref: '#/components/schemas/DomainString'
company_name:
$ref: '#/components/schemas/CompanyNameString'
linkedin:
$ref: '#/components/schemas/LinkedInString'
title_filter:
$ref: '#/components/schemas/TitleFilterNullableString'
title_filters:
type: array
items:
$ref: '#/components/schemas/TitleFilterRequest'
minItems: 1
maxItems: 5
examples:
- - name: founders
filter: founder OR co-founder OR ceo
description: >
Allows multiple title filters in order. Used only if `title_filter`
is not present. One of `title_filter` or `title_filters` is
required.
externalDocs:
url: https://docs.waterfall.io/v1/prospector-multiple-title-filters
location_name:
$ref: '#/components/schemas/LocationNameString'
location_country:
$ref: '#/components/schemas/LocationCountryString'
location_countries:
type:
- array
- "null"
items:
$ref: '#/components/schemas/LocationCountryString'
minItems: 0
maxItems: 50
examples:
- - United States
- Canada
description: List of possible countries of the contact's current address. If it is present it will be used instead of location_country.
externalDocs:
url: https://docs.waterfall.io/v1/prospector-location-filter
excluded_names:
type:
- array
- "null"
items:
$ref: '#/components/schemas/FullNameString'
minItems: 0
maxItems: 200
description: The list of names to exclude from results
examples:
- - Bill Gates
- Steve Ballmer
limit:
$ref: '#/components/schemas/LimitInteger'
include_phones:
$ref: '#/components/schemas/IncludePhonesBoolean'
verified_only:
type:
- boolean
- "null"
default: true
description: If not present or set to **true**, Waterfall will only return **safe to send** emails. If present and set to **false**, Waterfall will return both **safe to send** and **catch-all** emails. All emails including **catch-all** ones are verified to remove invalid, role, and spam-trap emails.
webhook_url:
$ref: '#/components/schemas/WebHookURLString'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
ProspectCreateResponse:
required:
- job_id
- start_date
type: object
description: Response returned when a prospector job is successfully launched.
properties:
job_id:
$ref: '#/components/schemas/UUIDString'
start_date:
$ref: '#/components/schemas/DataTimeString'
ProspectGetResponse:
required:
- status
- start_date
- input
type: object
description: Finder response with prospector job status, input, and optional output.
properties:
status:
$ref: '#/components/schemas/JobStatusEnum'
start_date:
$ref: '#/components/schemas/DataTimeString'
stop_date:
$ref: '#/components/schemas/DataTimeString'
input:
type: object
properties:
task:
type: object
properties:
domain:
$ref: '#/components/schemas/DomainString'
company_name:
$ref: '#/components/schemas/CompanyNameString'
webhook_url:
$ref: '#/components/schemas/WebHookURLString'
limit:
$ref: '#/components/schemas/LimitInteger'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
job_id:
$ref: '#/components/schemas/UUIDString'
context_id:
$ref: '#/components/schemas/UUIDString'
output:
type: object
properties:
company:
$ref: '#/components/schemas/Company'
persons:
type: array
maxItems: 500
items:
$ref: '#/components/schemas/Person'
usage:
$ref: '#/components/schemas/UsageBreakdown'
SearchContactRequest:
type: object
description: >
Request payload for Search Contact.
Search mode must be one of:
1) `contact_linkedin`
2) company-specific search with one of `domain`, `company_linkedin`, `company_name`
3) company-set search with one of `company_location_countries`, `company_industries`, or
`company_employee_ranges` (in this mode, `experience_start_date` or
`experience_start_date_new_hire` is required, and one of `title_filters` or
`title_lists` is required).
anyOf:
- type: object
properties:
contact_linkedin:
$ref: '#/components/schemas/LinkedInString'
required:
- contact_linkedin
- type: object
properties:
domain:
$ref: '#/components/schemas/DomainString'
required:
- domain
- type: object
properties:
company_linkedin:
$ref: '#/components/schemas/LinkedInString'
required:
- company_linkedin
- type: object
properties:
company_name:
$ref: '#/components/schemas/CompanyNameString'
required:
- company_name
- allOf:
- anyOf:
- type: object
properties:
company_location_countries:
type: array
items:
$ref: '#/components/schemas/LocationCountryString'
required:
- company_location_countries
- type: object
properties:
company_industries:
type: array
items:
type: string
required:
- company_industries
- type: object
properties:
company_employee_ranges:
type: array
items:
$ref: '#/components/schemas/SearchContactEmployeeRangeString'
required:
- company_employee_ranges
- anyOf:
- type: object
properties:
experience_start_date:
type: string
format: date
required:
- experience_start_date
- type: object
properties:
experience_start_date_new_hire:
type: string
format: date
required:
- experience_start_date_new_hire
- anyOf:
- type: object
properties:
title_filters:
type: array
items:
$ref: '#/components/schemas/TitleFilterRequest'
required:
- title_filters
- type: object
properties:
title_lists:
type: array
items:
$ref: '#/components/schemas/TitleListRequest'
required:
- title_lists
properties:
domain:
$ref: '#/components/schemas/DomainString'
company_linkedin:
$ref: '#/components/schemas/LinkedInString'
company_name:
$ref: '#/components/schemas/CompanyNameString'
contact_linkedin:
$ref: '#/components/schemas/LinkedInString'
excluded_names:
type:
- array
- "null"
minItems: 0
maxItems: 200
items:
$ref: '#/components/schemas/FullNameString'
description: Names to exclude from results.
examples:
- - Bill Gates
- Steve Ballmer
included_names:
type:
- array
- "null"
minItems: 0
maxItems: 100
items:
$ref: '#/components/schemas/FullNameString'
description: If provided, restrict results to these names.
examples:
- - Ada Lovelace
- Grace Hopper
title_filters:
type:
- array
- "null"
minItems: 0
maxItems: 5
items:
$ref: '#/components/schemas/TitleFilterRequest'
description: Boolean title filters.
examples:
- - name: founders
filter: founder OR co-founder OR ceo
title_lists:
type:
- array
- "null"
minItems: 0
maxItems: 5
items:
$ref: '#/components/schemas/TitleListRequest'
description: Named title lists.
examples:
- - name: founders
titles:
- founder
- co-founder
- ceo
departments:
type:
- array
- "null"
minItems: 0
items:
$ref: '#/components/schemas/DepartmentString'
description: Contact department filters.
examples:
- - Engineering
- Marketing
seniorities:
type:
- array
- "null"
minItems: 0
items:
$ref: '#/components/schemas/SeniorityString'
description: Contact seniority filters.
examples:
- - Manager
- Director
location_countries:
type:
- array
- "null"
minItems: 0
maxItems: 50
items:
$ref: '#/components/schemas/LocationCountryString'
description: Contact location countries.
examples:
- - United States
- Canada
company_location_countries:
type:
- array
- "null"
minItems: 0
maxItems: 50
items:
$ref: '#/components/schemas/LocationCountryString'
description: Company location countries.
examples:
- - United States
- Canada
company_industries:
type:
- array
- "null"
minItems: 0
maxItems: 50
items:
$ref: '#/components/schemas/SearchCompanyIndustryString'
description: Company industries.
examples:
- - Software Development
- Information Technology
company_employee_ranges:
type:
- array
- "null"
minItems: 0
maxItems: 8
items:
$ref: '#/components/schemas/SearchContactEmployeeRangeString'
description: Company employee size ranges.
examples:
- - "201-500"
- "501-1000"
experience_start_date:
type:
- string
- "null"
format: date
description: Find contacts who started their current role on or after the specified date (`YYYY-MM-DD`).
examples:
- "2024-01-01"
experience_start_date_new_hire:
type:
- string
- "null"
format: date
description: Find new hires who started their current role on or after the specified date (`YYYY-MM-DD`).
examples:
- "2025-01-01"
page_number:
$ref: '#/components/schemas/SearchContactPageNumberInteger'
page_size:
$ref: '#/components/schemas/SearchContactPageSizeInteger'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
SearchContactTaskInput:
description: Search Contact request fields echoed back with tracking identifiers.
allOf:
- $ref: '#/components/schemas/SearchContactRequest'
- type: object
properties:
job_id:
$ref: '#/components/schemas/UUIDString'
context_id:
$ref: '#/components/schemas/UUIDString'
SearchContactPersonExperience:
type: object
additionalProperties: false
description: Employment history entry returned in Search Contact results.
properties:
title:
type:
- string
- "null"
location:
type:
- string
- "null"
company_name:
type:
- string
- "null"
company_linkedin_id:
type:
- string
- "null"
company_linkedin_url:
type:
- string
- "null"
format: uri
company_domain:
type:
- string
- "null"
start_year:
type:
- integer
- "null"
format: int32
start_month:
type:
- integer
- "null"
format: int32
start_date:
type:
- string
- "null"
format: date
end_year:
type:
- integer
- "null"
format: int32
end_month:
type:
- integer
- "null"
format: int32
end_date:
type:
- string
- "null"
format: date
is_current:
type:
- boolean
- "null"
description:
type:
- string
- "null"
SearchContactPerson:
type: object
additionalProperties: false
description: Redacted person payload returned by Search Contact output.
required:
- id
- first_name
- last_name
- linkedin_id
- linkedin_url
- about
- personal_email
- location
- country
- company_id
- company_linkedin_id
- company_name
- company_domain
- professional_email
- mobile_phone
- phone_numbers
- title
- seniority
- department
- experiences
- email_verified
- email_confidence
- email_verified_status
- domain_age_days
- smtp_provider
- mx_record
properties:
id:
$ref: '#/components/schemas/UUIDString'
first_name:
type:
- string
- "null"
last_name:
type:
- string
- "null"
linkedin_id:
type:
- string
- "null"
linkedin_url:
type:
- string
- "null"
format: uri
about:
type:
- string
- "null"
personal_email:
type: "null"
location:
type:
- string
- "null"
country:
$ref: '#/components/schemas/LocationCountryString'
company_id:
anyOf:
- $ref: '#/components/schemas/UUIDString'
- type: "null"
company_linkedin_id:
type:
- string
- "null"
company_name:
type:
- string
- "null"
company_domain:
type:
- string
- "null"
professional_email:
type: "null"
mobile_phone:
type: "null"
phone_numbers:
type: array
maxItems: 0
items:
type: string
title:
type:
- string
- "null"
seniority:
anyOf:
- $ref: '#/components/schemas/SeniorityString'
- type: "null"
department:
anyOf:
- $ref: '#/components/schemas/DepartmentString'
- type: "null"
experiences:
type: array
items:
$ref: '#/components/schemas/SearchContactPersonExperience'
email_verified:
type:
- boolean
- "null"
email_confidence:
anyOf:
- $ref: '#/components/schemas/EmailConfidenceEnum'
- type: "null"
email_verified_status:
anyOf:
- $ref: '#/components/schemas/EmailStatusEnum'
- type: "null"
domain_age_days:
type:
- string
- "null"
smtp_provider:
type:
- string
- "null"
mx_record:
type:
- string
- "null"
SearchContactOutput:
type: object
description: Search Contact output payload.
properties:
persons:
type:
- array
- "null"
description: Person results with contact channels redacted.
items:
$ref: '#/components/schemas/SearchContactPerson'
usage:
$ref: '#/components/schemas/UsageBreakdown'
examples:
- persons: []
SearchContactGetResponse:
type: object
required:
- status
- start_date
- input
description: Search Contact response with job state, input, and optional output.
properties:
status:
$ref: '#/components/schemas/JobStatusEnum'
start_date:
$ref: '#/components/schemas/DataTimeString'
stop_date:
$ref: '#/components/schemas/DataTimeString'
input:
type: object
examples:
- task:
domain: waterfall.io
page_number: 1
page_size: 10
job_id: 7d44db58-5de3-4e92-a2fb-8325d12c2e8b
context_id: 7d44db58-5de3-4e92-a2fb-8325d12c2e8b
properties:
task:
$ref: '#/components/schemas/SearchContactTaskInput'
output:
$ref: '#/components/schemas/SearchContactOutput'
SearchCompanyRequest:
type: object
description: >
Request payload for Search Company.
At least one non-empty list among `industries`, `location_countries`,
or `sizes` must be provided.
anyOf:
- type: object
required:
- industries
properties:
industries:
type: array
minItems: 1
items:
$ref: '#/components/schemas/SearchCompanyIndustryString'
- type: object
required:
- location_countries
properties:
location_countries:
type: array
minItems: 1
items:
$ref: '#/components/schemas/SearchCompanyCountryString'
- type: object
required:
- sizes
properties:
sizes:
type: array
minItems: 1
items:
$ref: '#/components/schemas/SearchContactEmployeeRangeString'
properties:
industries:
type: array
minItems: 0
maxItems: 50
items:
$ref: '#/components/schemas/SearchCompanyIndustryString'
description: Industry filters used to match companies.
examples:
- - software development
- information technology and services
location_countries:
type: array
minItems: 0
maxItems: 50
items:
$ref: '#/components/schemas/SearchCompanyCountryString'
description: Country filters used to match companies.
examples:
- - United States
- Canada
sizes:
type: array
minItems: 0
maxItems: 8
items:
$ref: '#/components/schemas/SearchContactEmployeeRangeString'
description: LinkedIn employee-size buckets used to filter companies.
examples:
- - "201-500"
- "501-1000"
page_number:
$ref: '#/components/schemas/SearchCompanyPageNumberInteger'
page_size:
$ref: '#/components/schemas/SearchCompanyPageSizeInteger'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
SearchCompanyTaskInput:
description: Search Company request fields echoed back with tracking identifiers.
allOf:
- $ref: '#/components/schemas/SearchCompanyRequest'
- type: object
properties:
job_id:
$ref: '#/components/schemas/UUIDString'
context_id:
$ref: '#/components/schemas/UUIDString'
SearchCompanyOutput:
type: object
description: Search Company output payload.
properties:
companies:
oneOf:
- type: array
maxItems: 250
items:
$ref: '#/components/schemas/CompanyEnriched'
- type: object
additionalProperties: false
description: List of matched companies. Can be empty.
usage:
$ref: '#/components/schemas/UsageBreakdown'
examples:
- companies: []
SearchCompanyGetResponse:
type: object
required:
- status
- start_date
- input
description: Search Company response with job state, input, and optional output.
properties:
status:
$ref: '#/components/schemas/JobStatusEnum'
start_date:
$ref: '#/components/schemas/DataTimeString'
stop_date:
$ref: '#/components/schemas/DataTimeString'
input:
type: object
examples:
- task:
industries:
- software development
location_countries:
- United States
sizes:
- "201-500"
page_number: 1
page_size: 20
job_id: 7d44db58-5de3-4e92-a2fb-8325d12c2e8b
context_id: 7d44db58-5de3-4e92-a2fb-8325d12c2e8b
properties:
task:
$ref: '#/components/schemas/SearchCompanyTaskInput'
output:
$ref: '#/components/schemas/SearchCompanyOutput'
CompanyTitlesRequest:
type: object
description: >
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"]`.
anyOf:
- type: object
required:
- domain
properties:
domain:
$ref: '#/components/schemas/DomainString'
- type: object
required:
- company_linkedin
properties:
company_linkedin:
$ref: '#/components/schemas/LinkedInString'
properties:
domain:
anyOf:
- $ref: '#/components/schemas/DomainString'
- type: "null"
examples:
- example.com
company_linkedin:
$ref: '#/components/schemas/LinkedInString'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
page_number:
$ref: '#/components/schemas/CompanyTitlesPageNumberInteger'
raw_titles:
type: boolean
default: false
description: Return eligible titles with whitespace and duplicates preserved, ordered ascending by title text.
examples:
- domain: example.com
company_linkedin: null
custom_fields: {}
page_number: 1
raw_titles: false
- domain: example.com
company_linkedin: null
custom_fields: {}
page_number: 1
raw_titles: true
CompanyTitlesOutputPage:
type: object
description: Paginated Company Titles output for a succeeded job.
required:
- titles
- has_more_pages
properties:
titles:
type: array
maxItems: 50000
items:
type: string
description: Active titles for the matched company on this page.
has_more_pages:
type: boolean
description: True when additional pages exist after this page.
usage:
$ref: '#/components/schemas/UsageBreakdown'
examples:
- titles:
- Software Engineer
- VP Sales
has_more_pages: false
CompanyTitlesGetResponse:
type: object
required:
- status
- start_date
- input
description: Company Titles response with job state, input, and optional output.
properties:
status:
$ref: '#/components/schemas/JobStatusEnum'
start_date:
$ref: '#/components/schemas/DataTimeString'
stop_date:
$ref: '#/components/schemas/DataTimeString'
input:
type: object
examples:
- 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
properties:
task:
allOf:
- $ref: '#/components/schemas/CompanyTitlesRequest'
- type: object
properties:
job_id:
$ref: '#/components/schemas/UUIDString'
context_id:
$ref: '#/components/schemas/UUIDString'
output:
$ref: '#/components/schemas/CompanyTitlesOutputPage'
CompanyRevealRequest:
type: object
description: Request payload for Company Reveal.
required:
- ip
properties:
ip:
type: string
format: ipv4
examples:
- "8.8.8.8"
webhook_url:
anyOf:
- $ref: '#/components/schemas/WebHookURLString'
- type: "null"
example: https://example.com/webhook
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
CompanyRevealTaskInput:
type: object
description: Company Reveal request fields echoed back with tracking identifiers.
properties:
ip:
type: string
format: ipv4
examples:
- "8.8.8.8"
webhook_url:
anyOf:
- $ref: '#/components/schemas/WebHookURLString'
- type: "null"
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
job_id:
$ref: '#/components/schemas/UUIDString'
context_id:
$ref: '#/components/schemas/UUIDString'
CompanyRevealIPGeo:
type: object
description: IP geolocation details returned by Company Reveal.
properties:
city:
type:
- string
- "null"
state:
type:
- string
- "null"
country:
type:
- string
- "null"
CompanyRevealOutput:
type: object
description: Company Reveal output payload.
properties:
ip:
type:
- string
- "null"
format: ipv4
examples:
- "8.8.8.8"
type:
type:
- string
- "null"
enum:
- company
- education
- government
- isp
- null
confidence_score:
type:
- string
- "null"
enum:
- very_high
- high
- medium
- low
- null
ip_geo:
$ref: '#/components/schemas/CompanyRevealIPGeo'
company:
oneOf:
- $ref: '#/components/schemas/CompanyEnriched'
- type: object
additionalProperties: false
maxProperties: 0
usage:
$ref: '#/components/schemas/UsageBreakdown'
CompanyRevealGetResponse:
type: object
required:
- status
- start_date
- input
description: Company Reveal response with synchronous job envelope and output.
properties:
status:
$ref: '#/components/schemas/JobStatusEnum'
start_date:
$ref: '#/components/schemas/DataTimeString'
stop_date:
$ref: '#/components/schemas/DataTimeString'
input:
type: object
properties:
task:
$ref: '#/components/schemas/CompanyRevealTaskInput'
output:
$ref: '#/components/schemas/CompanyRevealOutput'
JobChangeStatusEnum:
type: string
description: Outcome of a Job Change check.
enum:
- left
- moved
- no_change
- unknown
examples:
- moved
JobChangeRequest:
type: object
description: >
Request payload for Job Change.
Valid input sets include:
1) `company_domain` + (`contact_linkedin`, `professional_email`,
`personal_email`, or `contact_full_name`)
2) `company_linkedin` + (`contact_linkedin`, `professional_email`, or
`personal_email`)
3) `professional_email` (optionally with `contact_full_name`)
anyOf:
- type: object
required:
- company_domain
- contact_linkedin
properties:
company_domain:
$ref: '#/components/schemas/DomainString'
contact_linkedin:
$ref: '#/components/schemas/LinkedInString'
- type: object
required:
- company_domain
- professional_email
properties:
company_domain:
$ref: '#/components/schemas/DomainString'
professional_email:
anyOf:
- $ref: '#/components/schemas/EmailString'
- type: "null"
- type: object
required:
- company_domain
- personal_email
properties:
company_domain:
$ref: '#/components/schemas/DomainString'
personal_email:
anyOf:
- $ref: '#/components/schemas/EmailString'
- type: "null"
- type: object
required:
- company_linkedin
- contact_linkedin
properties:
company_linkedin:
$ref: '#/components/schemas/LinkedInString'
contact_linkedin:
$ref: '#/components/schemas/LinkedInString'
- type: object
required:
- company_linkedin
- professional_email
properties:
company_linkedin:
$ref: '#/components/schemas/LinkedInString'
professional_email:
anyOf:
- $ref: '#/components/schemas/EmailString'
- type: "null"
- type: object
required:
- company_linkedin
- personal_email
properties:
company_linkedin:
$ref: '#/components/schemas/LinkedInString'
personal_email:
anyOf:
- $ref: '#/components/schemas/EmailString'
- type: "null"
- type: object
required:
- company_domain
- contact_full_name
properties:
company_domain:
$ref: '#/components/schemas/DomainString'
contact_full_name:
$ref: '#/components/schemas/FullNameString'
- type: object
required:
- professional_email
- contact_full_name
properties:
professional_email:
anyOf:
- $ref: '#/components/schemas/EmailString'
- type: "null"
contact_full_name:
$ref: '#/components/schemas/FullNameString'
- type: object
required:
- professional_email
properties:
professional_email:
anyOf:
- $ref: '#/components/schemas/EmailString'
- type: "null"
properties:
company_domain:
$ref: '#/components/schemas/DomainString'
company_linkedin:
$ref: '#/components/schemas/LinkedInString'
professional_email:
anyOf:
- $ref: '#/components/schemas/EmailString'
- type: "null"
examples:
- john.doe@waterfall.io
personal_email:
anyOf:
- $ref: '#/components/schemas/EmailString'
- type: "null"
examples:
- john.doe@gmail.com
contact_linkedin:
$ref: '#/components/schemas/LinkedInString'
contact_full_name:
$ref: '#/components/schemas/FullNameString'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
JobChangeTaskInput:
description: Job Change request fields echoed back with tracking identifiers.
allOf:
- $ref: '#/components/schemas/JobChangeRequest'
- type: object
properties:
job_id:
$ref: '#/components/schemas/UUIDString'
context_id:
$ref: '#/components/schemas/UUIDString'
JobChangeOutput:
type: object
description: Job Change output payload.
properties:
job_change_status:
$ref: '#/components/schemas/JobChangeStatusEnum'
person:
anyOf:
- $ref: '#/components/schemas/Person'
- type: object
additionalProperties: false
description: >
Contact profile with email and phone channels redacted. Empty object
when no matching contact profile was found.
usage:
$ref: '#/components/schemas/UsageBreakdown'
examples:
- job_change_status: unknown
person: {}
JobChangeGetResponse:
type: object
required:
- status
- start_date
- input
description: Job Change response with job state, input, and optional output.
properties:
status:
$ref: '#/components/schemas/JobStatusEnum'
start_date:
$ref: '#/components/schemas/DataTimeString'
stop_date:
$ref: '#/components/schemas/DataTimeString'
input:
type:
- object
- "null"
examples:
- task:
company_domain: scale.com
company_linkedin: null
professional_email: null
personal_email: null
contact_linkedin: null
contact_full_name: Connor Heggie
custom_fields: {}
job_id: 56d6add5-0bdd-4834-9b9b-390c08df31e9
context_id: 56d6add5-0bdd-4834-9b9b-390c08df31e9
properties:
task:
$ref: '#/components/schemas/JobChangeTaskInput'
output:
$ref: '#/components/schemas/JobChangeOutput'
EnrichmentContactCreateRequest:
anyOf:
- type: object
required: [ linkedin ]
properties:
linkedin:
$ref: '#/components/schemas/LinkedInString'
- type: object
required: [ full_name, domain ]
properties:
full_name:
$ref: '#/components/schemas/FullNameString'
domain:
$ref: '#/components/schemas/DomainString'
- type: object
required: [ first_name, last_name, domain ]
properties:
first_name:
$ref: '#/components/schemas/FirstNameString'
last_name:
$ref: '#/components/schemas/LastNameString'
domain:
$ref: '#/components/schemas/DomainString'
- type: object
required: [ email ]
properties:
email:
anyOf:
- $ref: '#/components/schemas/EmailString'
- type: "null"
type: object
description: Request payload to launch a contact enrichment job.
properties:
linkedin:
$ref: '#/components/schemas/LinkedInString'
full_name:
$ref: '#/components/schemas/FullNameString'
first_name:
$ref: '#/components/schemas/FirstNameString'
last_name:
$ref: '#/components/schemas/LastNameString'
domain:
$ref: '#/components/schemas/DomainString'
email:
$ref: '#/components/schemas/EmailString'
include_phones:
$ref: '#/components/schemas/IncludePhonesBoolean'
webhook_url:
$ref: '#/components/schemas/WebHookURLString'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
EnrichmentContactCreateResponse:
required:
- job_id
- start_date
type: object
description: Response returned when a contact enrichment job is successfully launched.
properties:
job_id:
$ref: '#/components/schemas/UUIDString'
start_date:
$ref: '#/components/schemas/DataTimeString'
EnrichmentContactGetResponse:
type: object
required:
- status
- start_date
- input
description: Finder response with contact enrichment job status, input, and optional output.
properties:
status:
$ref: '#/components/schemas/JobStatusEnum'
start_date:
$ref: '#/components/schemas/DataTimeString'
stop_date:
$ref: '#/components/schemas/DataTimeString'
input:
type:
- object
- "null"
properties:
task:
type: object
properties:
linkedin:
$ref: '#/components/schemas/LinkedInString'
full_name:
$ref: '#/components/schemas/FullNameString'
first_name:
$ref: '#/components/schemas/FirstNameString'
last_name:
$ref: '#/components/schemas/LastNameString'
domain:
$ref: '#/components/schemas/DomainString'
email:
type:
- string
- "null"
format: email
maxLength: 254
webhook_url:
$ref: '#/components/schemas/WebHookURLString'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
job_id:
$ref: '#/components/schemas/UUIDString'
context_id:
$ref: '#/components/schemas/UUIDString'
output:
type: object
properties:
person:
$ref: '#/components/schemas/Person'
usage:
$ref: '#/components/schemas/UsageBreakdown'
EnrichmentPhoneCreateRequest:
anyOf:
- type: object
required: [ linkedin ]
properties:
linkedin:
$ref: '#/components/schemas/LinkedInString'
- type: object
required: [ full_name, domain ]
properties:
full_name:
$ref: '#/components/schemas/FullNameString'
domain:
$ref: '#/components/schemas/DomainString'
- type: object
required: [ first_name, last_name, domain ]
properties:
first_name:
$ref: '#/components/schemas/FirstNameString'
last_name:
$ref: '#/components/schemas/LastNameString'
domain:
$ref: '#/components/schemas/DomainString'
- type: object
required: [ email ]
properties:
email:
anyOf:
- $ref: '#/components/schemas/EmailString'
- type: "null"
type: object
description: Request payload to launch a phone enrichment job.
properties:
linkedin:
$ref: '#/components/schemas/LinkedInString'
full_name:
$ref: '#/components/schemas/FullNameString'
first_name:
$ref: '#/components/schemas/FirstNameString'
last_name:
$ref: '#/components/schemas/LastNameString'
domain:
$ref: '#/components/schemas/DomainString'
email:
$ref: '#/components/schemas/EmailString'
webhook_url:
$ref: '#/components/schemas/WebHookURLString'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
EnrichmentPhoneCreateResponse:
required:
- job_id
- start_date
type: object
description: Response returned when a phone enrichment job is successfully launched.
properties:
job_id:
$ref: '#/components/schemas/UUIDString'
start_date:
$ref: '#/components/schemas/DataTimeString'
EnrichmentPhoneGetResponse:
type: object
required:
- status
- start_date
- input
description: Finder response with phone enrichment job status, input, and optional output.
properties:
status:
$ref: '#/components/schemas/JobStatusEnum'
start_date:
$ref: '#/components/schemas/DataTimeString'
stop_date:
$ref: '#/components/schemas/DataTimeString'
input:
type:
- object
- "null"
properties:
task:
type: object
properties:
linkedin:
$ref: '#/components/schemas/LinkedInString'
full_name:
$ref: '#/components/schemas/FullNameString'
first_name:
$ref: '#/components/schemas/FirstNameString'
last_name:
$ref: '#/components/schemas/LastNameString'
domain:
$ref: '#/components/schemas/DomainString'
email:
type:
- string
- "null"
format: email
maxLength: 254
webhook_url:
$ref: '#/components/schemas/WebHookURLString'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
job_id:
$ref: '#/components/schemas/UUIDString'
context_id:
$ref: '#/components/schemas/UUIDString'
output:
type: object
properties:
person:
$ref: '#/components/schemas/Person'
usage:
$ref: '#/components/schemas/UsageBreakdown'
UsageBreakdown:
type: object
description: >
Per-job cost breakdown and account balance snapshot for observability.
required:
- total_usd
- balance_remaining_usd
- persons_count
- persons_usd
- phones_count
- phones_usd
- companies_count
- companies_usd
properties:
total_usd:
type: number
examples:
- 0.12
balance_remaining_usd:
type: number
examples:
- 99.88
persons_count:
type: integer
format: int64
examples:
- 0
persons_usd:
type: number
examples:
- 0.0
phones_count:
type: integer
format: int64
examples:
- 1
phones_usd:
type: number
examples:
- 0.12
companies_count:
type: integer
format: int64
examples:
- 0
companies_usd:
type: number
examples:
- 0.0
Usage:
type: object
description: Usage counters for a given time window.
properties:
start_date:
type: string
format: date
description: Start of the reported UTC window, inclusive.
examples:
- "2024-10-01"
end_date:
type: string
format: date
description: End of the reported UTC window, exclusive.
examples:
- "2024-11-01"
prospector_requests:
type: integer
format: int64
examples:
- 10
prospector_persons:
type: integer
format: int64
examples:
- 17
prospector_persons_phones:
type: integer
format: int64
examples:
- 2
enrichment_contact_requests:
type: integer
format: int64
examples:
- 4827
enrichment_contact_persons:
type: integer
format: int64
examples:
- 2873
enrichment_contact_persons_phones:
type: integer
format: int64
examples:
- 85
enrichment_phone_requests:
type: integer
format: int64
examples:
- 2590
enrichment_phone_phones:
type: integer
format: int64
examples:
- 2279
enrichment_company_requests:
type: integer
format: int64
examples:
- 15
enrichment_company_companies:
type: integer
format: int64
examples:
- 15
search_contact_requests:
type: integer
format: int64
examples:
- 0
search_contact_found:
type: integer
format: int64
examples:
- 0
search_company_requests:
type: integer
format: int64
examples:
- 0
search_company_found:
type: integer
format: int64
examples:
- 0
company_reveal_requests:
type: integer
format: int64
examples:
- 0
company_reveal_found:
type: integer
format: int64
examples:
- 0
company_titles_requests:
type: integer
format: int64
description: Count of company titles requests (jobs) in the usage period.
examples:
- 0
company_titles_found:
type: integer
format: int64
description: Total titles returned across company titles jobs in the usage period.
examples:
- 0
job_change_requests:
type: integer
format: int64
examples:
- 0
job_change_found:
type: integer
format: int64
examples:
- 0
verify_email_requests:
type: integer
format: int64
examples:
- 0
verify_email_verified:
type: integer
format: int64
examples:
- 0
EnrichmentCompanyCreateRequest:
anyOf:
- type: object
required: [ domain ]
properties:
domain:
$ref: '#/components/schemas/DomainString'
- type: object
required: [ linkedin ]
properties:
linkedin:
$ref: '#/components/schemas/LinkedInString'
- type: object
required: [ name ]
properties:
name:
$ref: '#/components/schemas/CompanyNameString'
type: object
description: Request payload to launch a company enrichment job.
properties:
domain:
$ref: '#/components/schemas/DomainString'
linkedin:
$ref: '#/components/schemas/LinkedInString'
name:
$ref: '#/components/schemas/CompanyNameString'
webhook_url:
$ref: '#/components/schemas/WebHookURLString'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
EnrichmentCompanyCreateResponse:
required:
- job_id
- start_date
type: object
description: Response returned when a company enrichment job is successfully launched.
properties:
job_id:
$ref: '#/components/schemas/UUIDString'
start_date:
$ref: '#/components/schemas/DataTimeString'
EnrichmentCompanyGetResponse:
type: object
required:
- status
- start_date
- input
description: Finder response with company enrichment job status, input, and optional output.
properties:
status:
$ref: '#/components/schemas/JobStatusEnum'
start_date:
$ref: '#/components/schemas/DataTimeString'
stop_date:
$ref: '#/components/schemas/DataTimeString'
input:
type: object
properties:
task:
type: object
properties:
linkedin:
$ref: '#/components/schemas/LinkedInString'
domain:
$ref: '#/components/schemas/DomainString'
name:
anyOf:
- $ref: '#/components/schemas/CompanyNameString'
- type: "null"
webhook_url:
$ref: '#/components/schemas/WebHookURLString'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
job_id:
$ref: '#/components/schemas/UUIDString'
context_id:
$ref: '#/components/schemas/UUIDString'
output:
type: object
properties:
company:
$ref: '#/components/schemas/CompanyEnriched'
usage:
$ref: '#/components/schemas/UsageBreakdown'
VerifyEmailCreateRequest:
type: object
description: Request payload to verify a single email address.
required:
- email
properties:
email:
$ref: '#/components/schemas/EmailString'
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
VerifyEmailGetResponse:
type: object
description: Verify Email response with status, input, and optional verified email output.
required:
- status
- start_date
- input
properties:
status:
$ref: '#/components/schemas/JobStatusEnum'
start_date:
$ref: '#/components/schemas/DataTimeString'
stop_date:
$ref: '#/components/schemas/DataTimeString'
input:
type: object
properties:
task:
type: object
properties:
email:
type: string
format: email
maxLength: 254
examples:
- "emre@waterfall.io"
custom_fields:
$ref: '#/components/schemas/CustomFieldsObject'
job_id:
$ref: '#/components/schemas/UUIDString'
context_id:
$ref: '#/components/schemas/UUIDString'
output:
type: object
properties:
email:
$ref: '#/components/schemas/EmailOutput'
usage:
$ref: '#/components/schemas/UsageBreakdown'
AccountReporterV2Price:
type: object
description: >
Unit prices in USD keyed by their corresponding Account Reporter usage
field, derived from the latest payment row. Present only when the request
is authenticated with a master API key. May be an empty object when no
payment row exists. These are current prices, not the actual historical
prices in effect during the requested `month` or
`start_date`/`end_date` interval.
properties:
prospector_persons:
type: number
format: float
description: Unit price in USD for a Prospector person.
examples:
- 0.138
prospector_persons_phones:
type: number
format: float
description: Unit price in USD for a Prospector person phone.
examples:
- 0.32
enrichment_contact_persons:
type: number
format: float
description: Unit price in USD for a Contact Enrichment person.
examples:
- 0.138
enrichment_contact_persons_phones:
type: number
format: float
description: Unit price in USD for a Contact Enrichment person phone.
examples:
- 0.32
enrichment_phone_phones:
type: number
format: float
description: Unit price in USD for a Phone Enrichment phone.
examples:
- 0.32
enrichment_company_companies:
type: number
format: float
description: Unit price in USD for a Company Enrichment company.
examples:
- 0.138
search_contact_found:
type: number
format: float
description: Unit price in USD for a Search Contact found result.
examples:
- 0.04
search_company_found:
type: number
format: float
description: Unit price in USD for a Search Company found result.
examples:
- 0.04
company_reveal_found:
type: number
format: float
description: Unit price in USD for a Company Reveal found result.
examples:
- 0.05
company_titles_found:
type: number
format: float
description: Unit price in USD for a Company Titles found result.
examples:
- 0.0
job_change_found:
type: number
format: float
description: Unit price in USD for a Job Change found result.
examples:
- 0.1
verify_email_verified:
type: number
format: float
description: Unit price in USD for a verified Email Verification result.
examples:
- 0.02
AccountReporterV2GetResponse:
type: object
description: >
Account reporter response containing key-level and account-level usage
metrics. The optional `price` object is included only for master API
keys.
properties:
key_usage:
$ref: '#/components/schemas/Usage'
account_usage:
$ref: '#/components/schemas/Usage'
balance_remaining_usd:
type: number
format: float
description: >
The current account balance. This is a present-moment value, not a
balance as of or within the requested `month` or
`start_date`/`end_date` interval.
examples:
- 23.34
price:
$ref: '#/components/schemas/AccountReporterV2Price'
APIKey:
type: object
description: API key record including metadata and rate-limit settings.
required:
- api_key
- active
- notes
- master
- per_interval
- interval_seconds
properties:
api_key:
$ref: '#/components/schemas/UUIDString'
active:
type:
- boolean
- "null"
description: True if the API key is active, false otherwise.
examples:
- true
notes:
$ref: '#/components/schemas/APIKeyNoteString'
master:
type: boolean
description: True for the master key, false for sub-keys.
examples:
- false
per_interval:
type: integer
format: int32
description: Requests allowed per interval.
examples:
- 30
interval_seconds:
type:
- integer
- "null"
format: int32
description: Interval duration in seconds (always 60).
examples:
- 60
APIKeysGetResponse:
required:
- api_keys
type: object
description: Response containing the list of API keys for the authenticated account.
properties:
api_keys:
type:
- array
- "null"
description: Your account API keys
items:
$ref: '#/components/schemas/APIKey'
examples:
- - api_key: ad18e456-0dd7-45e1-b094-43a0361aedfa
active: true
notes: team-a
master: false
per_interval: 30
interval_seconds: 60
APIKeyCreateRequest:
type: object
description: Request payload to create a new sub API key.
required:
- notes
properties:
notes:
$ref: '#/components/schemas/APIKeyNoteString'
per_interval:
type: integer
format: int32
minimum: 1
default: 50
description: >
Optional per-interval request limit for the new sub-key. If omitted,
the current implementation defaults to 50. It cannot exceed the
master key's `per_interval`.
APIKeyModifyRequest:
type: object
description: Request payload to update an existing API key.
required:
- api_key
- notes
- active
properties:
api_key:
$ref: '#/components/schemas/UUIDString'
notes:
$ref: '#/components/schemas/APIKeyNoteString'
active:
type: boolean
default: true
description: Set to true to keep or mark the target sub-key active.
per_interval:
type: integer
format: int32
minimum: 1
examples:
- 25
description: >
Optional per-interval request limit for the target sub-key. If not
provided, current value is not changed. It cannot exceed the master
key's `per_interval`.
APIKeyModifyResponse:
type: object
description: Response payload for a successful API key update.
required:
- api_key
- active
- notes
- master
properties:
api_key:
$ref: '#/components/schemas/UUIDString'
active:
type:
- boolean
- "null"
examples:
- true
notes:
$ref: '#/components/schemas/APIKeyNoteString'
master:
type: boolean
examples:
- false
per_interval:
type: integer
format: int32
minimum: 1
examples:
- 25
ErrorCategory:
type: string
description: >
Stable high-level error category.
This value must match the prefix of `code` (for example, `VALIDATION` for
`VALIDATION_BAD_REQUEST`).
enum:
- AUTH
- PERMISSION
- QUOTA
- VALIDATION
- NOT_FOUND
- RATE_LIMIT
- ROUTING
- INTERNAL
examples:
- VALIDATION
ErrorCode:
type: string
description: >
Stable machine-readable error code.
Codes are grouped by category via prefix and always follow
`CATEGORY_DETAIL`. The prefix must match `category`.
pattern: '^(AUTH|PERMISSION|QUOTA|VALIDATION|NOT_FOUND|RATE_LIMIT|ROUTING|INTERNAL)_[A-Z0-9_]+$'
enum:
- AUTH_BAD_API_KEY
- AUTH_MISSING_API_KEY
- AUTH_NEED_MASTER_API_KEY
- PERMISSION_FEATURE_NOT_ENABLED
- PERMISSION_INCLUDE_PHONES_REQUIRES_PHONE_ENRICHMENT
- PERMISSION_NEED_ADMIN_API_KEY
- QUOTA_ACCOUNT_OVER_QUOTA
- VALIDATION_BAD_DOMAIN
- VALIDATION_BAD_DOMAIN_DISPOSABLE
- VALIDATION_BAD_DOMAIN_EMAIL_PROVIDER
- VALIDATION_BAD_DOMAIN_INVALID_CHARACTERS
- VALIDATION_BAD_DOMAIN_NO_MX
- VALIDATION_BAD_DOMAIN_PROVIDER_DOMAIN
- VALIDATION_BAD_DOMAIN_SERVICE_DOMAIN
- VALIDATION_BAD_DOMAIN_SOCIAL_MEDIA
- VALIDATION_BAD_DOMAIN_TOP_LEVEL
- VALIDATION_BAD_DOMAIN_URL_SHORTENER
- VALIDATION_BAD_EMAIL_CONSECUTIVE_DIGITS
- VALIDATION_BAD_EMAIL_INVALID
- VALIDATION_BAD_EMAIL_PERSONAL_NOT_ALLOWED
- VALIDATION_BAD_EMAIL_PROFESSIONAL_NOT_ALLOWED
- VALIDATION_BAD_EMAIL_ROLE
- VALIDATION_BAD_EMAIL_TOO_LONG
- VALIDATION_BAD_EMAIL_TOO_MANY_DIGITS
- VALIDATION_BAD_JOB_ID
- VALIDATION_BAD_NAME_INVALID
- VALIDATION_BAD_REQUEST
- VALIDATION_BAD_TITLE_FILTER
- VALIDATION_BAD_TITLE_FILTER_EXTRA_LEFT_PARENTHESIS
- VALIDATION_BAD_TITLE_FILTER_EXTRA_RIGHT_PARENTHESIS
- VALIDATION_BAD_TITLE_FILTER_EXTRA_STRING
- VALIDATION_BAD_TITLE_FILTER_MISSING_RIGHT_PARENTHESIS
- VALIDATION_BAD_TITLE_FILTER_MISSING_STRING
- VALIDATION_BAD_TITLE_FILTER_MISSING_STRING_OR_NOT_OR_LEFT_PARENTHESIS
- VALIDATION_CANNOT_EDIT_MASTER_API_KEY
- VALIDATION_MISSING_BODY
- VALIDATION_MISSING_JOB_ID_PARAMETER
- VALIDATION_MISSING_TITLE_FILTERS
- VALIDATION_SUBKEY_RATE_EXCEEDS_MASTER
- NOT_FOUND_ACCOUNT_OR_KEY_NOT_FOUND
- NOT_FOUND_API_KEY_NOT_FOUND
- NOT_FOUND_JOB_NOT_FOUND
- NOT_FOUND_NO_MASTER_API_KEY_FOUND
- NOT_FOUND_NOT_FOUND
- RATE_LIMIT_RATE_LIMIT_EXCEEDED
- ROUTING_INVALID_PATH_OR_METHOD
- INTERNAL_FAILED_CREATE_API_KEY
- INTERNAL_FAILED_EDIT_API_KEY
- INTERNAL_UNCLASSIFIED_ERROR
examples:
- VALIDATION_BAD_REQUEST
ErrorResponse:
required:
- status
- message
- category
- code
type: object
description: Standard error envelope returned by the API.
properties:
status:
type:
- string
- "null"
examples:
- error
message:
type: string
examples:
- Bad request
category:
$ref: "#/components/schemas/ErrorCategory"
code:
$ref: "#/components/schemas/ErrorCode"
error:
oneOf:
- type: array
maxItems: 10
items:
type: string
maxLength: 1000
- type: string
maxLength: 1000
examples:
- Rate limit exceeded
ErrorResponseUnauthorized:
description: Error response used when the API key header is missing.
required:
- status
- message
- category
- code
type: object
properties:
status:
type:
- string
- "null"
examples:
- error
message:
type: string
examples:
- Missing api key
category:
$ref: "#/components/schemas/ErrorCategory"
code:
$ref: "#/components/schemas/ErrorCode"
error:
oneOf:
- type: array
maxItems: 10
items:
type: string
maxLength: 1000
- type: string
maxLength: 1000
examples:
- Missing api key
ErrorResponseForbidden:
description: Error response used when the API key is invalid.
required:
- status
- message
- category
- code
type: object
properties:
status:
type:
- string
- "null"
examples:
- error
message:
type: string
examples:
- Bad api key
category:
$ref: "#/components/schemas/ErrorCategory"
code:
$ref: "#/components/schemas/ErrorCode"
error:
oneOf:
- type: array
maxItems: 10
items:
type: string
maxLength: 1000
- type: string
maxLength: 1000
examples:
- Bad api key
examples:
ProspectGetSucceeded:
summary: "SUCCEEDED - contacts found"
description: Completed prospector job with company profile, matched contacts, and usage billing.
value:
status: "SUCCEEDED"
start_date: "2024-06-18T13:53:21.181000+00:00"
stop_date: "2024-06-18T13:53:26.014000+00:00"
input:
task:
domain: "acme.com"
limit: 10
custom_fields: {}
job_id: "413b35ce-572e-4d3a-bff6-e52d4542361d"
context_id: "413b35ce-572e-4d3a-bff6-e52d4542361d"
output:
company:
id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
domain: "acme.com"
company_name: "Acme Corp"
website: "https://www.acme.com/"
linkedin_id: "acme-corp"
linkedin_url: "https://www.linkedin.com/company/acme-corp/"
linkedin_description: "Acme Corp builds enterprise software solutions for mid-market and large companies."
linkedin_logo_url: "https://media.licdn.com/dms/image/example/company-logo_200_200/logo.png"
size: "501-1000"
linkedin_size: "501-1000 employees"
linkedin_industry: "Software Development"
linkedin_type: "Privately Held"
linkedin_followers: 12500
linkedin_founded: 2010
linkedin_employees_count: 823
linkedin_address: "San Francisco, California, United States"
country: "United States"
generic_emails: []
persons:
- id: "e70fc5a3-55d9-43e5-93ea-b9e8210435da"
first_name: "Jane"
last_name: "Doe"
linkedin_id: "jane-doe-abc123"
linkedin_url: "https://www.linkedin.com/in/jane-doe-abc123/"
location: "San Francisco, California, United States"
country: "United States"
company_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
company_linkedin_id: "acme-corp"
company_name: "Acme Corp"
company_domain: "acme.com"
professional_email: "jane.doe@acme.com"
phone_numbers: []
title: "Head of Sales"
seniority: "Director"
department: "Sales"
experiences:
- title: "Head of Sales"
company_name: "Acme Corp"
company_linkedin_id: "acme-corp"
company_linkedin_url: "https://www.linkedin.com/company/acme-corp/"
company_domain: "acme.com"
start_year: 2021
start_month: 3
is_current: true
email_verified: true
email_confidence: "high"
email_verified_status: "safe"
smtp_provider: "Google"
mx_record: "aspmx.l.google.com"
usage:
total_usd: 0.10
balance_remaining_usd: 99.90
persons_count: 1
persons_usd: 0.10
phones_count: 0
phones_usd: 0.00
companies_count: 0
companies_usd: 0.00
ProspectGetRunning:
summary: "RUNNING - still processing"
description: In-progress prospector job with input echoed and no output yet.
value:
status: "RUNNING"
start_date: "2021-06-04T18:21:49.665000+00:00"
input:
task:
domain: "waterfall.io"
custom_fields: {}
job_id: "dae134ce-50e4-4208-b24f-f38687a09377"
context_id: "dae134ce-50e4-4208-b24f-f38687a09377"
SearchContactGetSucceeded:
summary: "SUCCEEDED - contacts found"
description: Completed search-contact job with filtered matches and usage billing.
value:
status: "SUCCEEDED"
start_date: "2024-01-15T12:00:00.000000+00:00"
stop_date: "2024-01-15T12:00:00.524000+00:00"
input:
task:
domain: "acme.com"
title_filters:
- name: sales_leaders
filter: "head of sales OR vp sales OR director of sales"
seniorities:
- "Director"
- "Vice President"
page_number: 1
page_size: 25
custom_fields: {}
job_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
context_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
output:
persons:
- id: "e70fc5a3-55d9-43e5-93ea-b9e8210435da"
first_name: "Jane"
last_name: "Doe"
linkedin_id: "jane-doe-abc123"
linkedin_url: "https://www.linkedin.com/in/jane-doe-abc123/"
about: null
personal_email: null
location: "San Francisco, California, United States"
country: "United States"
company_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
company_linkedin_id: "acme-corp"
company_name: "Acme Corp"
company_domain: "acme.com"
professional_email: null
mobile_phone: null
phone_numbers: []
title: "Head of Sales"
seniority: "Director"
department: "Sales"
experiences:
- title: "Head of Sales"
location: null
company_name: "Acme Corp"
company_linkedin_id: "acme-corp"
company_linkedin_url: "https://www.linkedin.com/company/acme-corp/"
company_domain: "acme.com"
start_year: 2021
start_month: 3
start_date: null
end_year: null
end_month: null
end_date: null
is_current: true
description: null
email_verified: null
email_confidence: null
email_verified_status: null
domain_age_days: null
smtp_provider: null
mx_record: null
usage:
total_usd: 0.10
balance_remaining_usd: 99.90
persons_count: 1
persons_usd: 0.10
phones_count: 0
phones_usd: 0.00
companies_count: 0
companies_usd: 0.00
EnrichmentContactGetSucceeded:
summary: "SUCCEEDED - contact found"
description: Completed contact enrichment job with enriched person profile and usage billing.
value:
status: "SUCCEEDED"
start_date: "2023-09-20T20:23:36.086988+00:00"
stop_date: "2023-09-20T20:23:51.892893+00:00"
input:
task:
linkedin: "https://www.linkedin.com/in/jane-doe-abc123/"
custom_fields: {}
job_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
context_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
output:
person:
id: "e70fc5a3-55d9-43e5-93ea-b9e8210435da"
first_name: "Jane"
last_name: "Doe"
linkedin_id: "jane-doe-abc123"
linkedin_url: "https://www.linkedin.com/in/jane-doe-abc123/"
location: "San Francisco, California, United States"
country: "United States"
company_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
company_linkedin_id: "acme-corp"
company_name: "Acme Corp"
company_domain: "acme.com"
professional_email: "jane.doe@acme.com"
phone_numbers: []
title: "Head of Sales"
seniority: "Director"
department: "Sales"
experiences:
- title: "Head of Sales"
company_name: "Acme Corp"
company_linkedin_id: "acme-corp"
company_linkedin_url: "https://www.linkedin.com/company/acme-corp/"
company_domain: "acme.com"
start_year: 2021
start_month: 3
is_current: true
email_verified: true
email_confidence: "high"
email_verified_status: "safe"
smtp_provider: "Google"
mx_record: "aspmx.l.google.com"
usage:
total_usd: 0.10
balance_remaining_usd: 99.90
persons_count: 1
persons_usd: 0.10
phones_count: 0
phones_usd: 0.00
companies_count: 0
companies_usd: 0.00
EnrichmentContactGetRunning:
summary: "RUNNING - still processing"
description: In-progress contact enrichment job with input echoed and no output yet.
value:
status: "RUNNING"
start_date: "2023-09-20T20:23:36.086988+00:00"
input:
task:
email: "jane.doe@acme.com"
custom_fields: {}
job_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
context_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
EnrichmentPhoneGetSucceeded:
summary: "SUCCEEDED - phone number found"
description: Completed phone enrichment job with E.164 phone number and usage billing.
value:
status: "SUCCEEDED"
start_date: "2024-01-15T12:00:00.000000+00:00"
stop_date: "2024-01-15T12:00:14.000000+00:00"
input:
task:
linkedin: "https://www.linkedin.com/in/jane-doe-abc123/"
custom_fields: {}
job_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
context_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
output:
person:
id: "e70fc5a3-55d9-43e5-93ea-b9e8210435da"
first_name: "Jane"
last_name: "Doe"
linkedin_id: "jane-doe-abc123"
linkedin_url: "https://www.linkedin.com/in/jane-doe-abc123/"
location: "San Francisco, California, United States"
country: "United States"
company_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
company_linkedin_id: "acme-corp"
company_name: "Acme Corp"
company_domain: "acme.com"
professional_email: "jane.doe@acme.com"
mobile_phone: "+14155550123"
phone_numbers:
- "+14155550123"
title: "Head of Sales"
seniority: "Director"
department: "Sales"
experiences:
- title: "Head of Sales"
company_name: "Acme Corp"
company_linkedin_id: "acme-corp"
company_linkedin_url: "https://www.linkedin.com/company/acme-corp/"
company_domain: "acme.com"
start_year: 2021
start_month: 3
is_current: true
email_verified: true
email_confidence: "high"
email_verified_status: "safe"
usage:
total_usd: 0.12
balance_remaining_usd: 99.88
persons_count: 0
persons_usd: 0.00
phones_count: 1
phones_usd: 0.12
companies_count: 0
companies_usd: 0.00
EnrichmentPhoneGetRunning:
summary: "RUNNING - still processing"
description: In-progress phone enrichment job with input echoed and no output yet.
value:
status: "RUNNING"
start_date: "2024-01-15T12:00:00.000000+00:00"
input:
task:
linkedin: "https://www.linkedin.com/in/jane-doe-abc123/"
custom_fields: {}
job_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
context_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
EnrichmentCompanyGetSucceeded:
summary: "SUCCEEDED - company found"
description: Completed company enrichment job with enriched company profile and usage billing.
value:
status: "SUCCEEDED"
start_date: "2024-01-15T12:00:00.000000+00:00"
stop_date: "2024-01-15T12:00:14.000000+00:00"
input:
task:
linkedin: "acme-corp"
custom_fields: {}
job_id: "0bc82c89-8905-49de-8077-da67f22c3145"
context_id: "0bc82c89-8905-49de-8077-da67f22c3145"
output:
company:
id: "8563b2e5-4090-49cf-a75b-4bbdedb4956f"
domain: "acme.com"
name: "Acme Corp"
website: "https://www.acme.com/"
linkedin_id: "acme-corp"
description: "Acme Corp builds enterprise software solutions for mid-market and large companies."
logo_url: "https://media.licdn.com/dms/image/example/company-logo_200_200/logo.png"
size: "501-1000"
employees_count: 823
industry: "Software Development"
type: "Privately Held"
founded: 2010
linkedin_url: "https://www.linkedin.com/company/acme-corp/"
funding_details:
total_funding_rounds: 0
total_funding_usd: 0
funding_rounds: []
country: "United States"
recent_job_posting_count: 12
technologies:
- "AWS"
- "Snowflake"
- "Salesforce"
usage:
total_usd: 0.05
balance_remaining_usd: 99.95
persons_count: 0
persons_usd: 0.00
phones_count: 0
phones_usd: 0.00
companies_count: 1
companies_usd: 0.05
EnrichmentCompanyGetRunning:
summary: "RUNNING - still processing"
description: In-progress company enrichment job with input echoed and no output yet.
value:
status: "RUNNING"
start_date: "2024-01-15T12:00:00.000000+00:00"
input:
task:
linkedin: "acme-corp"
custom_fields: {}
job_id: "0bc82c89-8905-49de-8077-da67f22c3145"
context_id: "0bc82c89-8905-49de-8077-da67f22c3145"
JobChangeGetMoved:
summary: "moved - contact is now at a new company"
description: Completed job-change check indicating the contact has moved employers.
value:
status: "SUCCEEDED"
start_date: "2025-03-28T22:44:23.566762+00:00"
stop_date: "2025-03-28T22:44:24.052251+00:00"
input:
task:
company_domain: "digitalriver.com"
professional_email: "jane.doe@digitalriver.com"
custom_fields: {}
job_id: "db1390dd-f2fa-4cb4-a77a-e651e785d12c"
context_id: "db1390dd-f2fa-4cb4-a77a-e651e785d12c"
output:
job_change_status: "moved"
person:
id: "e70fc5a3-55d9-43e5-93ea-b9e8210435da"
first_name: "Jane"
last_name: "Doe"
linkedin_id: "jane-doe-abc123"
linkedin_url: "https://www.linkedin.com/in/jane-doe-abc123/"
about: "Sales professional with a background in SaaS and enterprise software."
location: "San Francisco, California, United States"
country: "United States"
company_linkedin_id: "acme-corp"
company_name: "Acme Corp"
company_domain: "acme.com"
title: "Head of Sales"
seniority: "Director"
department: "Sales"
experiences:
- title: "Head of Sales"
location: "San Francisco, CA"
company_name: "Acme Corp"
company_linkedin_id: "acme-corp"
company_linkedin_url: "https://www.linkedin.com/company/acme-corp/"
company_domain: "acme.com"
start_year: 2023
start_month: 11
start_date: "2023-11-01"
is_current: true
- title: "Senior Account Executive"
location: "Remote"
company_name: "Digital River"
company_linkedin_id: "digital-river"
company_linkedin_url: "https://www.linkedin.com/company/digital-river/"
company_domain: "digitalriver.com"
start_year: 2019
start_month: 7
start_date: "2019-07-01"
end_year: 2023
end_month: 10
end_date: "2023-10-01"
is_current: false
usage:
total_usd: 0.05
balance_remaining_usd: 99.95
persons_count: 1
persons_usd: 0.05
phones_count: 0
phones_usd: 0.00
companies_count: 0
companies_usd: 0.00
JobChangeGetUnknown:
summary: "unknown - profile could not be verified"
description: Completed job-change check where the contact move status could not be verified.
value:
status: "SUCCEEDED"
start_date: "2025-10-30T08:44:03.724955+00:00"
stop_date: "2025-10-30T08:44:04.908156+00:00"
input:
task:
company_domain: "scale.com"
contact_full_name: "Connor Heggie"
custom_fields: {}
job_id: "56d6add5-0bdd-4834-9b9b-390c08df31e9"
context_id: "56d6add5-0bdd-4834-9b9b-390c08df31e9"
output:
job_change_status: "unknown"
person: {}
usage:
total_usd: 0.00
balance_remaining_usd: 100.00
persons_count: 0
persons_usd: 0.00
phones_count: 0
phones_usd: 0.00
companies_count: 0
companies_usd: 0.00
responses:
UnauthorizedResponse:
description: API key not provided within the headers.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponseUnauthorized"
example:
status: error
message: Missing api key
category: AUTH
code: AUTH_MISSING_API_KEY
error: Missing api key
ForbiddenResponse:
description: Wrong API key provided within the headers.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponseForbidden"
example:
status: error
message: Bad api key
category: AUTH
code: AUTH_BAD_API_KEY
error: Bad api key
PaymentRequiredResponse:
description: Account is over quota.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
status: error
message: Your account is over its quota. Please contact your account manager to discuss an upgrade.
category: QUOTA
code: QUOTA_ACCOUNT_OVER_QUOTA
BadRequestBodyOrInputResponse:
description: Bad request body or invalid input.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missing_body:
value:
status: error
message: Missing body
category: VALIDATION
code: VALIDATION_MISSING_BODY
bad_request:
value:
status: error
message: Bad request
category: VALIDATION
code: VALIDATION_BAD_REQUEST
error:
- "request: Value error, contact_linkedin cannot be set together with other fields"
BadRequestJobIdResponse:
description: Missing or malformed job_id parameter.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missing_job_id:
value:
status: error
message: Missing job_id parameter
category: VALIDATION
code: VALIDATION_MISSING_JOB_ID_PARAMETER
bad_job_id:
value:
status: error
message: Bad job_id dae134ce-50e4-4208-b24f-f38687a0937X
category: VALIDATION
code: VALIDATION_BAD_JOB_ID
JobNotFoundResponse:
description: The job_id does not exist.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
status: error
message: Job dae134ce-50e4-4208-b24f-f38687a09377 not found
category: NOT_FOUND
code: NOT_FOUND_JOB_NOT_FOUND
TooManyRequestsResponse:
description: Too many requests. Rate limit exceeded.
headers:
X-RateLimit-Limit:
description: Maximum number of requests allowed per interval.
schema:
type: integer
format: int32
minimum: 0
X-RateLimit-Remaining:
description: Remaining requests in the current interval.
schema:
type: integer
format: int32
minimum: 0
X-RateLimit-Interval:
description: Rate limit interval length in seconds.
schema:
type: number
minimum: 0
Retry-After:
description: Seconds to wait before retrying.
schema:
type: number
minimum: 0
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
status: error
message: Too many requests. Try again after 12.34 seconds
error: Rate limit exceeded
category: RATE_LIMIT
code: RATE_LIMIT_RATE_LIMIT_EXCEEDED
APIKeyBadRequestResponse:
description: Invalid API key management request body.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
status: error
message: Bad request
error:
- "notes: Field required"
category: VALIDATION
code: VALIDATION_BAD_REQUEST
paths:
/.well-known/jwks.json:
x-launch-stage: GA
get:
operationId: getWebhookJwks
summary: Webhook JWKS
description: >-
Public JSON Web Key Set for verifying Waterfall webhook signatures.
The response contains Ed25519 public keys and is cacheable for 300
seconds.
tags:
- webhook-authentication
security: []
responses:
"200":
description: Waterfall webhook verification keys.
headers:
Cache-Control:
description: Public JWKS cache lifetime.
schema:
type: string
enum:
- public, max-age=300
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookJwksResponse"
"404":
description: Invalid path.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"400":
description: Invalid request method.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
"500":
description: JWKS key configuration is unavailable or invalid.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
/v1/prospector:
x-launch-stage: GA
post:
operationId: addProspectorJob
summary: Prospector Launcher
description: >-
Launch stage: GA.
Launch a contact search using a domain, LinkedIn URL/ID, or company
name. `domain` is required, and one of `title_filter` or
`title_filters` is required.
Prospector workflow overview:
You input target account domains/LinkedIn URLs/IDs and persona (job
titles). You get contacts with job title, location, social profiles,
phone numbers, verified emails, and more.
tags:
- prospector
requestBody:
description: >
Request payload for Prospector Launcher. Includes required targeting
fields (`domain` + `title_filter` or `title_filters`) and optional
company identifier, location filters, `limit`, `include_phones`,
`verified_only`, `webhook_url`, and `custom_fields`. Because
processing is asynchronous, use the Finder endpoint or provide
`webhook_url` for callback delivery.
content:
application/json:
schema:
$ref: "#/components/schemas/ProspectCreateRequest"
example:
domain: waterfall.io
title_filter: founder OR ceo
limit: 10
include_phones: false
required: true
security:
- api_key: []
responses:
"200":
description: Prospector successfully launched.
content:
application/json:
schema:
$ref: "#/components/schemas/ProspectCreateResponse"
examples:
response:
value:
job_id: dae884ce-50aa-g208-b24f-f30687a00368
start_date: "2021-06-04T18:21:49.665000+00:00"
"400":
$ref: "#/components/responses/BadRequestBodyOrInputResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
get:
operationId: getProspectorJob
summary: Prospector Finder
description: >
Launch stage: GA.
This endpoint allows you to get the result of a launch on the Prospector
Launcher endpoint, using the provided job_id returned as the output of
the Prospector Launcher API call.
tags:
- prospector
parameters:
- $ref: '#/components/parameters/JobIdQueryParameter'
responses:
"200":
description: >
Prospector job state, input, and any available output data.
content:
application/json:
schema:
$ref: "#/components/schemas/ProspectGetResponse"
examples:
succeeded:
$ref: "#/components/examples/ProspectGetSucceeded"
running:
$ref: "#/components/examples/ProspectGetRunning"
"400":
$ref: "#/components/responses/BadRequestJobIdResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
$ref: "#/components/responses/JobNotFoundResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
security:
- api_key: []
/v1/search/contact:
x-launch-stage: GA
post:
operationId: addSearchContactJob
summary: Search Contact Launcher
description: >
Launch stage: GA.
Launch a Search Contact job and return the result payload.
The request supports three search modes:
1) by `contact_linkedin`
2) by company identity (`domain`, `company_linkedin`, or `company_name`)
3) by company-set filters (`company_location_countries`, `company_industries`,
or `company_employee_ranges`) with experience/title constraints.
tags:
- search-contact
requestBody:
description: Search Contact request payload with filters and pagination options.
content:
application/json:
schema:
$ref: "#/components/schemas/SearchContactRequest"
examples:
company_domain:
value:
domain: waterfall.io
title_filters:
- name: founders
filter: founder OR co-founder OR ceo
page_number: 1
page_size: 10
required: true
security:
- api_key: []
responses:
"200":
description: Search Contact result returned successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/SearchContactGetResponse"
examples:
succeeded:
summary: "SUCCEEDED - contacts found"
value:
status: "SUCCEEDED"
start_date: "2025-02-05T15:46:35.771751+00:00"
stop_date: "2025-02-05T15:46:37.111111+00:00"
input:
task:
domain: "waterfall.io"
page_number: 1
page_size: 10
custom_fields: {}
job_id: "7d44db58-5de3-4e92-a2fb-8325d12c2e8b"
context_id: "7d44db58-5de3-4e92-a2fb-8325d12c2e8b"
output:
persons:
- id: "e70fc5a3-55d9-43e5-93ea-b9e8210435da"
first_name: "Jane"
last_name: "Doe"
linkedin_id: "jane-doe-abc123"
linkedin_url: "https://www.linkedin.com/in/jane-doe-abc123/"
about: null
personal_email: null
location: "San Francisco, California, United States"
country: "United States"
company_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
company_linkedin_id: "waterfall-io"
company_name: "Waterfall"
company_domain: "waterfall.io"
professional_email: null
mobile_phone: null
phone_numbers: []
title: "Head of Sales"
seniority: "Director"
department: "Sales"
experiences:
- title: "Head of Sales"
location: null
company_name: "Waterfall"
company_linkedin_id: "waterfall-io"
company_linkedin_url: "https://www.linkedin.com/company/waterfall-io/"
company_domain: "waterfall.io"
start_year: 2021
start_month: 3
start_date: null
end_year: null
end_month: null
end_date: null
is_current: true
description: null
email_verified: null
email_confidence: null
email_verified_status: null
domain_age_days: null
smtp_provider: null
mx_record: null
usage:
total_usd: 0.10
balance_remaining_usd: 99.90
persons_count: 1
persons_usd: 0.10
phones_count: 0
phones_usd: 0.00
companies_count: 0
companies_usd: 0.00
"400":
$ref: "#/components/responses/BadRequestBodyOrInputResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
get:
operationId: getSearchContactJob
summary: Search Contact Finder
description: >
Launch stage: GA.
Retrieve Search Contact job state and result by `job_id`.
tags:
- search-contact
parameters:
- $ref: '#/components/parameters/JobIdQueryParameter'
security:
- api_key: []
responses:
"200":
description: Search Contact job state, input, and any available output.
content:
application/json:
schema:
$ref: "#/components/schemas/SearchContactGetResponse"
examples:
succeeded:
$ref: "#/components/examples/SearchContactGetSucceeded"
"400":
$ref: "#/components/responses/BadRequestJobIdResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
$ref: "#/components/responses/JobNotFoundResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
/v1/enrichment/contact:
x-launch-stage: GA
post:
operationId: addEnrichmentContactJob
summary: Contact Enrichment Launcher
description: >
Launch stage: GA.
Launch a contact enrichment job.
Accepted payload categories are LinkedIn URL/ID, email, or
full-name/domain (or first-name/last-name/domain).
If email is provided, Waterfall performs email-based enrichment. If
email is missing but LinkedIn is present, Waterfall performs
LinkedIn-based enrichment. Otherwise it performs name+domain enrichment.
Using a professional email generally provides better enrichment quality.
tags:
- enrichment-contact
requestBody:
description: >
Contact enrichment payload: provide one identifier strategy
(`linkedin`, `email`, `full_name` + `domain`, or `first_name` +
`last_name` + `domain`) plus optional `include_phones`,
`webhook_url`, and `custom_fields`.
content:
application/json:
schema:
$ref: "#/components/schemas/EnrichmentContactCreateRequest"
example:
email: james.dev@gmail.com
custom_fields:
crm_id: crm_208
record_id: usr_1042
tier: free
required: true
security:
- api_key: []
responses:
"200":
description: Contact enrichment job successfully launched.
content:
application/json:
schema:
$ref: "#/components/schemas/EnrichmentContactCreateResponse"
examples:
response:
value:
job_id: dae884ce-50aa-g208-b24f-f30687a00368
start_date: "2021-06-04T18:21:49.665000+00:00"
"400":
$ref: "#/components/responses/BadRequestBodyOrInputResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
get:
operationId: getEnrichmentContactJob
summary: Enrichment Contact Finder
description: >
Launch stage: GA.
This endpoint allows you to get the result of a launch on the Contact
Enrichment Launcher endpoint, using the provided job_id returned as the
output of the Contact Enrichment Launcher API call.
tags:
- enrichment-contact
parameters:
- $ref: '#/components/parameters/JobIdQueryParameter'
responses:
"200":
description: >
Contact enrichment job state, input, and any available output person.
content:
application/json:
schema:
$ref: "#/components/schemas/EnrichmentContactGetResponse"
examples:
succeeded:
$ref: "#/components/examples/EnrichmentContactGetSucceeded"
running:
$ref: "#/components/examples/EnrichmentContactGetRunning"
"400":
$ref: "#/components/responses/BadRequestJobIdResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
$ref: "#/components/responses/JobNotFoundResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
security:
- api_key: []
/v1/enrichment/phone:
x-launch-stage: GA
post:
operationId: addEnrichmentPhoneJob
summary: Phone Enrichment Launcher
description: >-
Launch stage: GA.
Launch a phone enrichment job.
Accepted payload categories are LinkedIn URL/ID, email, or
full-name/domain (or first-name/last-name/domain).
If LinkedIn is present, Waterfall performs LinkedIn-to-phone enrichment.
If LinkedIn is absent and email is present, Waterfall performs
email-based enrichment. Otherwise it performs name+domain to phone
enrichment.
LinkedIn-based enrichment generally provides the best quality. You are
only charged when a number is returned.
tags:
- enrichment-phone
requestBody:
description: >
Phone enrichment payload: provide one identifier strategy
(`linkedin`, `email`, `full_name` + `domain`, or `first_name` +
`last_name` + `domain`) plus optional `webhook_url` and
`custom_fields`.
content:
application/json:
schema:
$ref: "#/components/schemas/EnrichmentPhoneCreateRequest"
example:
linkedin: waterfall-io
domain: waterfall.io
required: true
security:
- api_key: []
responses:
"200":
description: Phone enrichment job successfully launched.
content:
application/json:
schema:
$ref: "#/components/schemas/EnrichmentPhoneCreateResponse"
examples:
response:
value:
job_id: dae884ce-50aa-g208-b24f-f30687a00368
start_date: "2021-06-04T18:21:49.665000+00:00"
"400":
$ref: "#/components/responses/BadRequestBodyOrInputResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
get:
operationId: getEnrichmentPhoneJob
summary: Enrichment Phone Finder
description: >-
Launch stage: GA.
This endpoint allows you to get the result of a launch on the Phone
Enrichment Launcher endpoint, using the provided job_id returned as the
output of the Phone Enrichment Launcher API call.
The phone numbers will always be in E.164 format.
The enrichment phone will return the result in the same format as the
enrich contact but with fewer fields populated.
tags:
- enrichment-phone
parameters:
- $ref: '#/components/parameters/JobIdQueryParameter'
responses:
"200":
description: >
Phone enrichment job state, input, and any available output person.
content:
application/json:
schema:
$ref: "#/components/schemas/EnrichmentPhoneGetResponse"
examples:
succeeded:
$ref: "#/components/examples/EnrichmentPhoneGetSucceeded"
running:
$ref: "#/components/examples/EnrichmentPhoneGetRunning"
"400":
$ref: "#/components/responses/BadRequestJobIdResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
$ref: "#/components/responses/JobNotFoundResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
security:
- api_key: []
/v1/enrichment/company:
x-launch-stage: GA
post:
operationId: addEnrichmentCompanyJob
summary: Company Enrichment Launcher
description: >
Launch stage: GA.
Launch a company enrichment job.
Accepted payload categories are LinkedIn URL/ID, domain, or company
name.
Name-based enrichment has the lowest quality and highest chance of
false positives. Prefer LinkedIn URL/ID or domain when possible.
tags:
- enrichment-company
requestBody:
description: >
Company enrichment payload: provide one company identifier (`domain`,
`linkedin`, or `name`) plus optional `webhook_url` and
`custom_fields`.
content:
application/json:
schema:
$ref: "#/components/schemas/EnrichmentCompanyCreateRequest"
required: true
security:
- api_key: []
responses:
"200":
description: Company enrichment job successfully launched.
content:
application/json:
schema:
$ref: "#/components/schemas/EnrichmentCompanyCreateResponse"
examples:
response:
value:
job_id: dae884ce-50aa-g208-b24f-f30687a00368
start_date: "2021-06-04T18:21:49.665000+00:00"
"400":
$ref: "#/components/responses/BadRequestBodyOrInputResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
get:
operationId: getEnrichmentCompanyJob
summary: Enrichment Company Finder
description: >
Launch stage: GA.
This endpoint allows you to get the result of a launch on the Company
Enrichment Launcher endpoint, using the provided job_id returned as the
output of the Company Enrichment Launcher API call.
tags:
- enrichment-company
parameters:
- $ref: '#/components/parameters/JobIdQueryParameter'
responses:
"200":
description: >
Company enrichment job state, input, and any available output company.
content:
application/json:
schema:
$ref: "#/components/schemas/EnrichmentCompanyGetResponse"
examples:
succeeded:
$ref: "#/components/examples/EnrichmentCompanyGetSucceeded"
running:
$ref: "#/components/examples/EnrichmentCompanyGetRunning"
"400":
$ref: "#/components/responses/BadRequestJobIdResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
$ref: "#/components/responses/JobNotFoundResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
security:
- api_key: []
/v1/search/company:
x-launch-stage: Preview
post:
operationId: addSearchCompanyJob
summary: Search Company Launcher
description: >
Launch stage: Preview.
Launch a Search Company job and return the result payload.
At least one non-empty list among `industries`, `location_countries`,
or `sizes` must be provided.
tags:
- search-company
requestBody:
description: >
Search Company request payload with company filters, pagination, and
optional `custom_fields`.
content:
application/json:
schema:
$ref: "#/components/schemas/SearchCompanyRequest"
examples:
by_industry_country_size:
value:
industries:
- software development
location_countries:
- United States
sizes:
- "201-500"
page_number: 1
page_size: 20
required: true
security:
- api_key: []
responses:
"200":
description: Search Company result returned successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/SearchCompanyGetResponse"
examples:
succeeded:
summary: "SUCCEEDED - companies found"
value:
status: "SUCCEEDED"
start_date: "2025-02-05T15:46:35.771751+00:00"
stop_date: "2025-02-05T15:46:37.111111+00:00"
input:
task:
industries:
- "Software Development"
location_countries:
- "United States"
sizes:
- "201-500"
page_number: 1
page_size: 20
custom_fields: {}
job_id: "7d44db58-5de3-4e92-a2fb-8325d12c2e8b"
context_id: "7d44db58-5de3-4e92-a2fb-8325d12c2e8b"
output:
companies:
- id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
domain: "acme.com"
name: "Acme Corp"
website: "acme.com"
linkedin_id: "acme-corp"
description: "Acme Corp builds software solutions for modern sales teams."
logo_url: "https://media.licdn.com/dms/image/acme-corp-logo.png"
size: "201-500"
employees_count: 350
industry: "Software Development"
type: "Privately Held"
founded: 2010
address: "100 Market St, San Francisco, California 94105, US"
country: "United States"
linkedin_url: "https://www.linkedin.com/company/acme-corp/"
linkedin_followers: 12500
crunchbase_url: null
funding_details:
total_funding_rounds: 0
total_funding_usd: 0
funding_rounds: []
recent_job_posting_count: 12
technologies:
- "AWS"
- "Snowflake"
usage:
total_usd: 0.05
balance_remaining_usd: 99.95
persons_count: 0
persons_usd: 0.00
phones_count: 0
phones_usd: 0.00
companies_count: 1
companies_usd: 0.05
"400":
$ref: "#/components/responses/BadRequestBodyOrInputResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
get:
operationId: getSearchCompanyJob
summary: Search Company Finder
description: >
Launch stage: Preview.
Retrieve Search Company job state and result by `job_id`.
tags:
- search-company
parameters:
- $ref: '#/components/parameters/JobIdQueryParameter'
security:
- api_key: []
responses:
"200":
description: Search Company job state, input, and any available output.
content:
application/json:
schema:
$ref: "#/components/schemas/SearchCompanyGetResponse"
examples:
succeeded:
summary: "SUCCEEDED - companies found"
value:
status: "SUCCEEDED"
start_date: "2024-01-15T12:00:00.000000+00:00"
stop_date: "2024-01-15T12:00:01.843000+00:00"
input:
task:
industries:
- "Software Development"
location_countries:
- "United States"
sizes:
- "201-500"
page_number: 1
page_size: 20
custom_fields: {}
job_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
context_id: "4fa6b97b-55d0-49fb-924b-16f4c1b6b03e"
output:
companies:
- id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
domain: "acme.com"
name: "Acme Corp"
website: "acme.com"
linkedin_id: "acme-corp"
description: "Acme Corp builds software solutions for modern sales teams."
logo_url: "https://media.licdn.com/dms/image/acme-corp-logo.png"
size: "201-500"
employees_count: 350
industry: "Software Development"
type: "Privately Held"
founded: 2010
address: "100 Market St, San Francisco, California 94105, US"
country: "United States"
linkedin_url: "https://www.linkedin.com/company/acme-corp/"
linkedin_followers: 12500
crunchbase_url: null
funding_details:
total_funding_rounds: 0
total_funding_usd: 0
funding_rounds: []
recent_job_posting_count: 12
technologies:
- "AWS"
- "Snowflake"
usage:
total_usd: 0.05
balance_remaining_usd: 99.95
persons_count: 0
persons_usd: 0.00
phones_count: 0
phones_usd: 0.00
companies_count: 1
companies_usd: 0.05
"400":
$ref: "#/components/responses/BadRequestJobIdResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
$ref: "#/components/responses/JobNotFoundResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
/v1/company-reveal:
x-launch-stage: Preview
get:
operationId: getCompanyRevealJob
summary: Company Reveal Finder
description: >
Launch stage: Preview.
Retrieve a persisted Company Reveal job using the `job_id` returned by
the Company Reveal Launcher.
tags:
- company-reveal
parameters:
- $ref: '#/components/parameters/JobIdQueryParameter'
responses:
"200":
description: Company Reveal job state and output returned successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyRevealGetResponse"
example:
status: SUCCEEDED
start_date: "2026-03-07T10:00:00.000000+00:00"
stop_date: "2026-03-07T10:00:00.300000+00:00"
input:
task:
ip: 8.8.8.8
webhook_url: null
custom_fields: {}
job_id: b7e4648f-4f15-4f2f-9d09-7af635ce6c24
context_id: b7e4648f-4f15-4f2f-9d09-7af635ce6c24
output:
ip: 8.8.8.8
type: company
confidence_score: high
ip_geo:
city: San Francisco
state: California
country: United States
company:
id: 54fa90d8-7ba7-4b6d-b5ec-82ee3e184166
domain: stripe.com
name: Stripe
website: stripe.com
linkedin_id: stripe
description: Stripe is a financial infrastructure platform for businesses.
logo_url: null
size: "5001-10000"
employees_count: 8000
industry: Financial Services
type: Privately Held
founded: 2010
address: 354 Oyster Point Blvd, South San Francisco, California 94080, US
country: United States
linkedin_url: https://www.linkedin.com/company/stripe/
linkedin_followers: 1500000
crunchbase_url: https://www.crunchbase.com/organization/stripe
funding_details:
total_funding_rounds: 0
total_funding_usd: 0
funding_rounds: []
recent_job_posting_count: 0
technologies: []
usage:
total_usd: 0.07
balance_remaining_usd: 99.93
persons_count: 0
persons_usd: 0.00
phones_count: 0
phones_usd: 0.00
companies_count: 1
companies_usd: 0.07
"400":
$ref: "#/components/responses/BadRequestJobIdResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
$ref: "#/components/responses/JobNotFoundResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
security:
- api_key: []
post:
operationId: addCompanyRevealJob
summary: Company Reveal Launcher
description: >
Launch stage: Preview.
Reveal company information for an IPv4 address, persist the job, and
return the result using Waterfall's synchronous job envelope format.
tags:
- company-reveal
requestBody:
description: Company Reveal request payload.
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyRevealRequest"
example:
ip: 8.8.8.8
required: true
security:
- api_key: []
responses:
"200":
description: Company Reveal result returned successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyRevealGetResponse"
example:
status: SUCCEEDED
start_date: "2026-03-07T10:00:00.000000+00:00"
stop_date: "2026-03-07T10:00:00.300000+00:00"
input:
task:
ip: 8.8.8.8
webhook_url: null
custom_fields: {}
job_id: b7e4648f-4f15-4f2f-9d09-7af635ce6c24
context_id: b7e4648f-4f15-4f2f-9d09-7af635ce6c24
output:
ip: 8.8.8.8
type: company
confidence_score: high
ip_geo:
city: San Francisco
state: California
country: United States
company:
id: 54fa90d8-7ba7-4b6d-b5ec-82ee3e184166
domain: stripe.com
name: Stripe
website: stripe.com
linkedin_id: stripe
description: Stripe is a financial infrastructure platform for businesses.
logo_url: null
size: "5001-10000"
employees_count: 8000
industry: Financial Services
type: Privately Held
founded: 2010
address: 354 Oyster Point Blvd, South San Francisco, California 94080, US
country: United States
linkedin_url: https://www.linkedin.com/company/stripe/
linkedin_followers: 1500000
crunchbase_url: https://www.crunchbase.com/organization/stripe
funding_details:
total_funding_rounds: 0
total_funding_usd: 0
funding_rounds: []
recent_job_posting_count: 0
technologies: []
usage:
total_usd: 0.07
balance_remaining_usd: 99.93
persons_count: 0
persons_usd: 0.00
phones_count: 0
phones_usd: 0.00
companies_count: 1
companies_usd: 0.07
"400":
$ref: "#/components/responses/BadRequestBodyOrInputResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
/v1/company-titles:
x-launch-stage: Preview
get:
operationId: getCompanyTitlesJob
summary: Company Titles Finder
description: >
Launch stage: Preview.
Requires the API key to have company titles access enabled for the account.
Retrieve Company Titles job state and result by `job_id`. The result uses the `raw_titles` mode selected when the job was launched. For stored values `"Engineer"`, `"Engineer "`, `"Engineer"`, and `"Manager"`, default mode returns `["Engineer", "Manager"]`; `raw_titles: true` returns `["Engineer", "Engineer", "Engineer ", "Manager"]`.
tags:
- company-titles
parameters:
- $ref: '#/components/parameters/JobIdQueryParameter'
security:
- api_key: []
responses:
"200":
description: Company Titles job state, input, and any available output.
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyTitlesGetResponse"
example:
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.70
balance_remaining_usd: 99.30
persons_count: 0
persons_usd: 0.00
phones_count: 0
phones_usd: 0.00
companies_count: 1
companies_usd: 0.70
"400":
$ref: "#/components/responses/BadRequestJobIdResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
$ref: "#/components/responses/JobNotFoundResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
post:
operationId: addCompanyTitlesJob
summary: Company Titles Launcher
description: >
Launch stage: Preview.
Requires the API key to have company titles access enabled for the account.
When the company resolves and at least one active title is returned, usage is billed as one successful lookup at the contracted company titles rate.
Launch a Company Titles job and return the result payload. 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 remain excluded. For stored values `"Engineer"`, `"Engineer "`, `"Engineer"`, and `"Manager"`, default mode returns `["Engineer", "Manager"]`; `raw_titles: true` returns `["Engineer", "Engineer", "Engineer ", "Manager"]`.
tags:
- company-titles
requestBody:
description: Company Titles request payload.
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyTitlesRequest"
examples:
by_domain:
value:
domain: example.com
custom_fields: {}
page_number: 1
raw_titles: false
by_company_linkedin:
value:
company_linkedin: waterfall-io
custom_fields: {}
page_number: 1
raw_titles: false
raw_titles:
value:
domain: example.com
custom_fields: {}
page_number: 1
raw_titles: true
required: true
security:
- api_key: []
responses:
"200":
description: Company Titles result returned successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/CompanyTitlesGetResponse"
example:
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.70
balance_remaining_usd: 99.30
persons_count: 0
persons_usd: 0.00
phones_count: 0
phones_usd: 0.00
companies_count: 1
companies_usd: 0.70
"400":
$ref: "#/components/responses/BadRequestBodyOrInputResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
description: Company was not found for the provided identifiers.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
status: error
message: Company not found
category: NOT_FOUND
code: NOT_FOUND_NOT_FOUND
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
/v1/job/change:
x-launch-stage: Preview
post:
operationId: addJobChangeJob
summary: Job Change Launcher
description: >
Launch stage: Preview.
Launch a Job Change check and return the result payload.
Valid request inputs include company + contact identifiers or a
standalone professional email.
tags:
- job-change
requestBody:
description: >
Job Change request payload with company/person identifiers and
optional `custom_fields`.
content:
application/json:
schema:
$ref: "#/components/schemas/JobChangeRequest"
examples:
by_company_domain_and_linkedin:
value:
company_domain: scale.com
contact_linkedin: connor-heggie
by_professional_email_only:
value:
professional_email: john.doe@waterfall.io
required: true
security:
- api_key: []
responses:
"200":
description: Job Change result returned successfully.
content:
application/json:
schema:
$ref: "#/components/schemas/JobChangeGetResponse"
examples:
moved:
$ref: "#/components/examples/JobChangeGetMoved"
unknown:
$ref: "#/components/examples/JobChangeGetUnknown"
"400":
$ref: "#/components/responses/BadRequestBodyOrInputResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
get:
operationId: getJobChangeJob
summary: Job Change Finder
description: >
Launch stage: Preview.
Retrieve Job Change job state and result by `job_id`.
tags:
- job-change
parameters:
- $ref: '#/components/parameters/JobIdQueryParameter'
security:
- api_key: []
responses:
"200":
description: Job Change job state, input, and any available output.
content:
application/json:
schema:
$ref: "#/components/schemas/JobChangeGetResponse"
examples:
moved:
$ref: "#/components/examples/JobChangeGetMoved"
unknown:
$ref: "#/components/examples/JobChangeGetUnknown"
"400":
$ref: "#/components/responses/BadRequestJobIdResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
$ref: "#/components/responses/JobNotFoundResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
/v1/verify/email:
x-launch-stage: GA
post:
operationId: addVerifyEmailJob
summary: Email Verifier
description: >
Launch stage: GA.
Verify a single email address. Unlike other endpoints, this endpoint
returns the verification result directly (no polling by `job_id`).
tags:
- verify-email
requestBody:
description: >
Verify Email payload. Requires a single `email` address and accepts
optional `custom_fields`.
content:
application/json:
schema:
$ref: "#/components/schemas/VerifyEmailCreateRequest"
required: true
security:
- api_key: []
responses:
"200":
description: Email verification result returned immediately.
content:
application/json:
schema:
$ref: "#/components/schemas/VerifyEmailGetResponse"
examples:
response:
value:
status: SUCCEEDED
start_date: "2021-06-04T18:21:49.665000+00:00"
stop_date: "2021-06-04T18:21:50.665000+00:00"
input:
task:
email: john.doe@waterfall.io
custom_fields: {}
job_id: dae884ce-50aa-g208-b24f-f30687a00368
context_id: dae884ce-50aa-g208-b24f-f30687a00368
output:
email:
email: john.doe@waterfall.io
domain: waterfall.io
email_status: valid
smtp_provider: Google
mx_records:
- aspmx.l.google.com
usage:
total_usd: 0.01
balance_remaining_usd: 99.99
persons_count: 1
persons_usd: 0.01
phones_count: 0
phones_usd: 0.00
companies_count: 0
companies_usd: 0.00
"400":
$ref: "#/components/responses/BadRequestBodyOrInputResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
/v2/account:
x-launch-stage: GA
get:
summary: Account Reporter V2
description: >
Launch stage: GA.
Get Waterfall usage information for both the authenticated API key and
the full account. Values differ when multiple keys exist under one
account. When authenticated with a master API key, the response also
includes a `price` object with unit prices in USD from the latest
payment. Sub-keys and single keys do not receive `price`. This call is
free.
By default, or when `month` is given, usage is scoped to one calendar
month. Alternatively, pass `start_date` and `end_date` together to
scope usage to a custom UTC date interval: `start_date` is inclusive,
`end_date` is exclusive, and the interval cannot exceed 12 months.
`start_date`/`end_date` are mutually exclusive with `month` — combining
them, or supplying only one of `start_date`/`end_date`, is a bad
request. The requested interval is echoed back in the response
`start_date`/`end_date` fields.
Whether given via `month` or `start_date`/`end_date`, the interval's
start must not be more than 12 months before the current UTC date, and
the interval must not be entirely in the future — at least one day of
the interval must be today (UTC) or earlier.
Usage is aggregated from daily records keyed by the UTC date usage was
recorded on; this endpoint does not provide sub-day reporting or a
guaranteed original request-start timestamp. `balance_remaining_usd`
is always the current account balance, and for master keys `price` is
always the latest-payment unit price — neither is scoped to, or a
historical value for, the requested interval.
tags:
- account
parameters:
- $ref: '#/components/parameters/MonthQueryParameter'
- $ref: '#/components/parameters/StartDateQueryParameter'
- $ref: '#/components/parameters/EndDateQueryParameter'
security:
- api_key: []
responses:
"200":
description: >
Success. Returns usage for the authenticated key and account. Master
API keys also receive unit prices in `price`.
content:
application/json:
schema:
$ref: "#/components/schemas/AccountReporterV2GetResponse"
examples:
master_key:
summary: Master key response including unit prices
value:
key_usage:
start_date: "2024-02-01"
end_date: "2024-03-01"
prospector_requests: 1
prospector_persons: 0
prospector_persons_phones: 0
enrichment_contact_requests: 0
enrichment_contact_persons: 0
enrichment_contact_persons_phones: 0
enrichment_phone_requests: 0
enrichment_phone_phones: 0
enrichment_company_requests: 0
enrichment_company_companies: 0
verify_email_requests: 0
verify_email_verified: 0
search_contact_requests: 1
search_contact_found: 0
account_usage:
start_date: "2024-02-01"
end_date: "2024-03-01"
prospector_requests: 2
prospector_persons: 0
prospector_persons_phones: 0
enrichment_contact_requests: 0
enrichment_contact_persons: 0
enrichment_contact_persons_phones: 0
enrichment_phone_requests: 0
enrichment_phone_phones: 0
enrichment_company_requests: 0
enrichment_company_companies: 0
verify_email_requests: 0
verify_email_verified: 0
search_contact_requests: 2
search_contact_found: 0
balance_remaining_usd: 99.90
price:
prospector_persons: 0.138
prospector_persons_phones: 0.32
enrichment_contact_persons: 0.138
enrichment_contact_persons_phones: 0.32
enrichment_phone_phones: 0.32
enrichment_company_companies: 0.138
search_contact_found: 0.04
search_company_found: 0.04
company_reveal_found: 0.05
company_titles_found: 0.0
job_change_found: 0.1
verify_email_verified: 0.02
sub_key:
summary: Sub-key response without unit prices
value:
key_usage:
start_date: "2024-02-01"
end_date: "2024-03-01"
prospector_requests: 1
prospector_persons: 0
prospector_persons_phones: 0
enrichment_contact_requests: 0
enrichment_contact_persons: 0
enrichment_contact_persons_phones: 0
enrichment_phone_requests: 0
enrichment_phone_phones: 0
enrichment_company_requests: 0
enrichment_company_companies: 0
verify_email_requests: 0
verify_email_verified: 0
search_contact_requests: 1
search_contact_found: 0
account_usage:
start_date: "2024-02-01"
end_date: "2024-03-01"
prospector_requests: 2
prospector_persons: 0
prospector_persons_phones: 0
enrichment_contact_requests: 0
enrichment_contact_persons: 0
enrichment_contact_persons_phones: 0
enrichment_phone_requests: 0
enrichment_phone_phones: 0
enrichment_company_requests: 0
enrichment_company_companies: 0
verify_email_requests: 0
verify_email_verified: 0
search_contact_requests: 2
search_contact_found: 0
balance_remaining_usd: 99.90
custom_interval:
summary: >
Sub-key response for a custom `start_date`/`end_date`
interval (e.g. `?start_date=2025-01-01&end_date=2025-01-15`)
value:
key_usage:
start_date: "2025-01-01"
end_date: "2025-01-15"
prospector_requests: 1
prospector_persons: 0
prospector_persons_phones: 0
enrichment_contact_requests: 0
enrichment_contact_persons: 0
enrichment_contact_persons_phones: 0
enrichment_phone_requests: 0
enrichment_phone_phones: 0
enrichment_company_requests: 0
enrichment_company_companies: 0
verify_email_requests: 0
verify_email_verified: 0
search_contact_requests: 1
search_contact_found: 0
account_usage:
start_date: "2025-01-01"
end_date: "2025-01-15"
prospector_requests: 2
prospector_persons: 0
prospector_persons_phones: 0
enrichment_contact_requests: 0
enrichment_contact_persons: 0
enrichment_contact_persons_phones: 0
enrichment_phone_requests: 0
enrichment_phone_phones: 0
enrichment_company_requests: 0
enrichment_company_companies: 0
verify_email_requests: 0
verify_email_verified: 0
search_contact_requests: 2
search_contact_found: 0
balance_remaining_usd: 99.90
"400":
description: >
Invalid query parameters. Includes: malformed `month` or
`start_date`/`end_date`; `month` combined with `start_date` or
`end_date`; only one of `start_date`/`end_date` supplied;
`end_date` not strictly after `start_date`; an interval longer
than 12 months; an interval start more than 12 months before the
current UTC date; or an interval entirely in the future.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
status: error
message: Bad request
category: VALIDATION
code: VALIDATION_BAD_REQUEST
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
description: Account or key not found.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
status: error
message: Account or key not found
category: NOT_FOUND
code: NOT_FOUND_ACCOUNT_OR_KEY_NOT_FOUND
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
operationId: getAccountInfo
/v1/api-keys:
x-launch-stage: GA
get:
summary: Get API keys
description: >
Launch stage: GA.
Get a list of API keys for the account. This endpoint requires
authentication with a master API key.
tags:
- api-keys
security:
- api_key: []
responses:
"200":
description: API keys list returned
content:
application/json:
schema:
$ref: "#/components/schemas/APIKeysGetResponse"
example:
api_keys:
- api_key: ad18e456-0dd7-45e1-b094-43a0361aedfa
active: true
notes: team-a
master: false
per_interval: 30
interval_seconds: 60
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"4XX":
description: Client error (for example missing/invalid API key or non-master key).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
operationId: getApiKeys
post:
operationId: addApiKey
summary: Create a new API key
description: >
Launch stage: GA.
Create a new API key for the account. This endpoint requires
authentication with a master API key.
tags:
- api-keys
requestBody:
description: >
Create sub-key payload. `notes` is required. `per_interval` is
optional; if omitted, the current implementation defaults to 50. The
value cannot exceed the master key's `per_interval`.
content:
application/json:
schema:
$ref: '#/components/schemas/APIKeyCreateRequest'
example:
notes: team-a
per_interval: 30
required: true
security:
- api_key: []
responses:
"200":
description: API key succesfully created.
content:
application/json:
schema:
$ref: "#/components/schemas/APIKey"
example:
api_key: ad18e456-0dd7-45e1-b094-43a0361aedfa
active: true
notes: team-a
master: false
per_interval: 30
interval_seconds: 60
"400":
$ref: "#/components/responses/APIKeyBadRequestResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
description: Master API key not found.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
status: error
message: No master api key found. Please contact your account manager to discuss an upgrade.
category: NOT_FOUND
code: NOT_FOUND_NO_MASTER_API_KEY_FOUND
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
"500":
description: Failed to create API key.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
status: error
message: Failed to create api key
category: INTERNAL
code: INTERNAL_FAILED_CREATE_API_KEY
put:
operationId: modifyApiKey
summary: Modify an API key
description: >
Launch stage: GA.
Modify an existing API key. This endpoint requires authentication with a
master API key.
Only **notes**, **active**, and **per_interval**
can be edited for an existing key.
The master key cannot be
edited.
tags:
- api-keys
requestBody:
description: >
Update API key payload. `api_key`, `notes`, and `active` are required.
Optional `per_interval` updates the sub-key rate limit; if omitted,
current `per_interval` is retained.
content:
application/json:
schema:
$ref: "#/components/schemas/APIKeyModifyRequest"
example:
api_key: ad18e456-0dd7-45e1-b094-43a0361aedfa
notes: updated note
active: true
per_interval: 25
required: true
security:
- api_key: []
responses:
"200":
description: API key succesfully updated.
content:
application/json:
schema:
$ref: "#/components/schemas/APIKeyModifyResponse"
example:
api_key: ad18e456-0dd7-45e1-b094-43a0361aedfa
active: true
notes: updated note
master: false
per_interval: 25
"400":
$ref: "#/components/responses/APIKeyBadRequestResponse"
"401":
$ref: "#/components/responses/UnauthorizedResponse"
"403":
$ref: "#/components/responses/ForbiddenResponse"
"402":
$ref: "#/components/responses/PaymentRequiredResponse"
"404":
description: API key or master API key not found.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missing_master:
value:
status: error
message: No master api key found. Please contact your account manager to discuss an upgrade.
category: NOT_FOUND
code: NOT_FOUND_NO_MASTER_API_KEY_FOUND
missing_api_key:
value:
status: error
message: Api key not found
category: NOT_FOUND
code: NOT_FOUND_API_KEY_NOT_FOUND
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
"500":
description: Failed to edit API key.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
status: error
message: Failed to edit api key
category: INTERNAL
code: INTERNAL_FAILED_EDIT_API_KEY
tags:
- name: prospector
description: Prospector
externalDocs:
description: Prospector endpoint docs
url: https://docs.waterfall.io/v1/prospector-launcher
- name: enrichment-contact
description: Enrichment Contact
externalDocs:
description: Contact enrichment endpoint docs
url: https://docs.waterfall.io/v1/contact-enrichment-launcher
- name: search-contact
description: Search Contact
externalDocs:
description: Search Contact endpoint docs
url: https://docs.waterfall.io/v1/search-contact-launcher
- name: search-company
description: Search Company
externalDocs:
description: Search Company endpoint docs
url: https://docs.waterfall.io/v1/search-company-launcher
- name: company-reveal
description: Company Reveal
- name: company-titles
description: Company Titles
- name: job-change
description: Job Change
externalDocs:
description: Job Change endpoint docs
url: https://docs.waterfall.io/v1/job-change-launcher
- name: enrichment-phone
description: Enrichment Phone
externalDocs:
description: Phone enrichment endpoint docs
url: https://docs.waterfall.io/v1/phone-enrichment-launcher
- name: enrichment-company
description: Enrichment Company
externalDocs:
description: Company enrichment endpoint docs
url: https://docs.waterfall.io/v1/company-enrichment-launcher
- name: verify-email
description: Verify Email
externalDocs:
description: Verify Email endpoint docs
url: https://docs.waterfall.io/v1/email-verifier
- name: account
description: Account
externalDocs:
description: Account Reporter endpoint docs
url: https://docs.waterfall.io/v1/account-reporter-v2
- name: api-keys
description: Api Keys Management **Enterprise Feature**
externalDocs:
description: API key management endpoint docs
url: https://docs.waterfall.io/v1/api-keys-overview
- name: webhook-authentication
description: Webhook Authentication
externalDocs:
description: Find out more about Waterfall API
url: https://docs.waterfall.io/v1/introduction
servers:
- url: https://api.waterfall.io
description: The production API server