Waterfall API offers a suite of features, available through seven calls in V1. Most endpoints are asynchronous, so you’ll need to launch a job (POST) and then fetch (GET) the results. Webhooks are supported to streamline this process. Here’s an overview of our endpoints:
\nFind 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.
\nProspector 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.
Enrich contact information by inputting professional/personal emails, LinkedIn URL/slug, or name + domain. Get enriched data like verified emails, job titles, and locations.
\nContact 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.
Enrich company data by inputting a domain, LinkedIn URL/slug, or company name. Receive details like headcount, industry, and headquarters.
\nCompany 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.
Get mobile numbers by inputting an email, LinkedIn URL/slug, or name + domain.
\nPhone 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.
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.
\nProvides information about your account's usage.
\nUse a single master key to manage all your API keys: create new keys, activate/deactivate them, and view all your keys in one place.
\nTo access the API, you need the API key provided in your contract. You can ask for multiple API keys for different teams' usage.
\nAll API request URLs start with https://api.waterfall.io/v1/. The API key needs to be provided in the header of the request as x-waterfall-api-key.
The Prospector, Enrichment 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.
\nThe maximum number of requests you can make per interval. Only sent when the rate limit is reached.
\nThe length of the interval in seconds. Only sent when the rate limit is reached.
\nThe number of seconds to wait until the rate limit window resets. Only sent when the rate limit is reached.
\nWaterfall offers three filtering options for prospect requests:
\nThe title_filter parameter allows to request specific titles with each request. How it works:
If it is present it must not be empty.
\nIf it is present and not empty, like \"title_filter\": \"((accountant) OR (accounting)) AND NOT(intern)\", Waterfall will filter employees using that title filter
If it is not present, Waterfall will try to use title_filters. One of \"title_filter\" or \"title_filters\" must be present.
If neither title_filters is present Waterfall will use your existing configured filters. To change your configured filters, contact your account manager.
The filter can be any Boolean expression. Accepted operators are: AND, OR NOT. Operators must be written with capital letters and separated by spaces.
\nThere is no need to enclose multi-word titles in parenthesis.
\nMatching for each title is inclusive. For example:
\nmanager will match program mamanger, 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
Few examples of valid filters:
\nmanager
\nmanager AND NOT project manager
\nmanager AND NOT (project manager OR sales manager)
\n( (manager OR director) AND (sales OR marketing) ) AND NOT ( project manager OR sales manager)
\n(accountant OR accounting) AND NOT intern
\n( (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) ) )
\nFew examples of invalid filters:
\nmangerANDdirector: 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 parenthesis to make sure the order of evaluation is what you intend and to make the expression more easy to read.
\nFor 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.
\nThe title_filters parameter allows requesting multiple title_filters in a specific order. It is used if title_filter is not present.
Example:
\n\"title_filters\": [\n {\n \"name\": \"ceo level\",\n \"filter\": \"ceo OR founder OR owner\"\n },\n {\n \"name\": \"sales\",\n \"filter\": \"revenue or growth OR sales\"\n },\n {\n \"name\": \"marketing or operations\",\n \"filter\": \"marketing OR operations\"\n }\n ]\n\nWaterfall will try each filter in the order provided up to the requested limit.
The location-based search is performed using two parameters: location_country and location_name.
The location_country parameter represents the country of the contact's current address. The country must be exact, like United States or France. Partial matches like United or Saudi will not work. The canonical list of countries is here.
An empty parameter is ignored.
\nLocation_countries
\nThe location_countries parameter is a list of countries where the contact's current address can be. If it is present and not empty it will be used instead of location_country Examples:
[\"France\"]
\n[\"France\", \"Germany\"]
\nFull list of coutries can be found here.
\nThe location_name the 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 comprises a city, region/state, and country. Partial matches are possible. Acceptable partial locations are:
\ncity, 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. Region filter tends to match most results.
\nAn empty parameter is ignored.
\nThe waterfall API uses conventional HTTP response codes to indicate the success or failure of a request, with detailed information in case of error.
\nContact Support:
Email: felix@waterfall.io
This endpoint allows you to launch a contact search, using a given domain, LinkedIn URL/ID or a company name. The domain input and title_filter or title_filters are required.
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.
\n","urlObject":{"path":["v1","prospector"],"host":["https://api.waterfall.io"],"query":[{"description":{"content":"(Required) The unique job_id you want to query. Has previously been returned in the output of the Prospector Launcher API call.
\n","type":"text/plain"},"key":"job_id","value":"\n\n","_postman_id":"42cfbbb1-e0e7-49d0-b4d1-522043ad73b4"},{"name":"enrichment","item":[{"name":"contact","item":[{"name":"Contact Enrichment Launcher","id":"d9f883bd-90e9-4639-b9d5-b9d7337718d9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"x-waterfall-api-key"},{"key":"value","value":"{{apiKey}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"linkedin\": \"officia aliqua Lorem\"\n}","options":{"raw":{"headerFamily":"json","language":"json"}}},"url":"https://api.waterfall.io/v1/enrichment/contact","description":"Prospector Workflow (Launcher & Finder) Overview
\n
You input: Target account domains/LinkedIn URLs/IDs and persona (job titles)
You get: Contacts with job titles, location, social media profiles, phone numbers, verified emails, and more
This endpoint allows you to launch a contact enrichment.
\nThis will accept three categories of payloads: a LinkedIn URL/ID, an email, or a full name plus an email domain.
\nIf the email is present, Waterfall will perform email-based enrichment.
\nIf the email is absent but the LinkedIn URL/ID is present, Waterfall will perform linkedin-based enrichment.
\nIf both the LinkedIn URL/ID and email are absent, Waterfall will perform name+domain to email enrichment.
\nNote that using a professional email provides significantly better results for email to business profile enrichment.
\n","urlObject":{"path":["v1","enrichment","contact"],"host":["https://api.waterfall.io"],"query":[],"variable":[]}},"response":[{"id":"2e32201d-f9d5-446f-93e9-6c61f53c0989","name":"Enrichment successfully launched.","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"description":"Added as a part of security scheme: apikey","key":"x-waterfall-api-key","value":"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.
\n","urlObject":{"path":["v1","enrichment","contact"],"host":["https://api.waterfall.io"],"query":[{"description":{"content":"(Required) The unique job_id you want to query. Has previously been returned in the output of the Enrichment Contact Launcher API call.
\n","type":"text/plain"},"key":"job_id","value":"