About Waterfall
What is Waterfall used for?
Waterfall.io is a B2B data API for go-to-market workflows. Use Waterfall to find people at target accounts, enrich contact and company records, match emails to business profiles, find phone numbers, verify email addresses, and check job changes.Who is Waterfall for?
Waterfall serves growth, revenue, and go-to-market teams. GTM engineers build prospecting workflows, revenue operations teams fill gaps in CRM records, and product-led growth teams add business context to signups. Developers can also add contact and company data to GTM tools, recruitment platforms, CRMs, marketing software, and other products.Who are Waterfall.io’s customers?
Waterfall.io’s current and past customers include Ramp, Gorgias, Zapier, Lightfield, JOIN, awork, Coverflex, Netic, 360Learning, Rippling, and ClickUp.What does Waterfall’s multi-vendor approach mean?
Waterfall combines 30+ data vendors through one API. Coverage varies by provider, so a contact or field missing from one source may be available from another. We evaluate providers on coverage, accuracy, freshness, and cost, and add or remove them as their performance changes. Your team maintains one integration and one set of agreed Waterfall rates, without managing separate vendor connections and contracts. Changes to the vendor mix do not change those rates. Your total cost depends on the services and options you use and your request volume.Is Waterfall a CRM or an outreach platform?
The Waterfall API supplies data for your CRM, product, or outreach workflow. Your integration decides where to save that data, which records to update, and when to send a message. Calling an enrichment endpoint does not create a CRM automation or send outreach.Is Waterfall secure?
Waterfall has undergone a SOC 2 Type II audit covering Security, Confidentiality, and Privacy. Independent auditors also conduct our penetration tests. Those auditors also work with Snowflake and T-Mobile. Our infrastructure runs on AWS, with encryption in transit and at rest. The API supports signed webhooks so your receiving system can verify that a delivery came from Waterfall and that its payload was not changed. Webhook signing depends on the signing configuration. Your receiver should verify the signature and reject unsigned deliveries when your workflow requires verification. The Webhook Verification guide explains the checks. For audit scope and security documentation, contact our team.Does Waterfall reuse or resell the data I submit?
We use the data you submit to the API to fulfil your requests. We do not resell those inputs, repurpose them for other customers, or add them to a shared enrichment database. Job results are saved so you can retrieve them later. For retention requirements, contact our team.Choosing a capability
What information do I need to get started?
The starting input depends on the Waterfall capability:
Use Choose an API to select the endpoint, then follow its reference for the accepted field names and combinations.
Can I turn an email address into a professional profile?
Yes. Contact Enrichment accepts anemail and returns available profile data after the job completes. The result can include name, title, company, LinkedIn, location, and employment history. Use the returned fields in your own qualification rules; see signup enrichment for the workflow.
Can I enrich a personal email address, such as Gmail?
Yes. Waterfall Contact Enrichment accepts professional and personal email addresses. A professional email generally gives better enrichment quality. Personal email support does not guarantee a match or every profile field, so test the types of signups you receive. See the Contact Enrichment reference.Can I find an email address if I only have a name or LinkedIn profile?
You can search with a LinkedIn profile. A name also needs a company domain. Contact Enrichment acceptslinkedin, full_name + domain, or first_name + last_name + domain. It returns available contact data, including a professional email and its verification fields.
Should I send all the identifiers I have for a person?
Choose the identifier strategy for the endpoint. Contact Enrichment uses email first, then LinkedIn, then name and domain. Phone Enrichment uses LinkedIn first, then email, then name and domain. Supplying several identifiers does not ask these endpoints to cross-check them or try each one in sequence. Your integration controls any later attempt with another supported identifier.How do I find decision-makers at a company?
Use Waterfall Prospector with the company domain and atitle_filter or named title_filters. Add location filters if your target roles are limited to a region. Prospector returns matching contacts with available email data and optional phone enrichment. Review the person’s role against your buying criteria; a title match alone does not establish purchasing authority. See account prospecting.
What is the difference between Search Contact and Prospector?
Waterfall Search Contact finds professional profiles and returns results in the same response. It supports a LinkedIn lookup, searches within a company, and searches across company sets with the required filters. It does not return email addresses or phone numbers. Prospector finds contacts at a company domain using title filters and optional location filters. It runs asynchronously and returns available contact details, with optional phone enrichment. Use Search Contact when you want to select profiles first; use Prospector when your task calls for contacts and their contact details. See account prospecting.Can I search for people across companies by role or hire date?
Yes. Use Search Contact in company-set mode. Supply a company filter (company_location_countries, company_industries, or company_employee_ranges), a date (experience_start_date or experience_start_date_new_hire), and title_filters or title_lists. The result contains profiles without email or phone channels. See company-set searches and hiring dates for a complete request.
Can I see the job titles available at a company?
Yes. Company Titles acceptsdomain or company_linkedin and returns the active titles available in Waterfall’s data. Select relevant titles and pass them in title_lists to Search Contact to find matching profiles. Company Titles is in Preview. It returns role names, not open job vacancies or an employee directory.
How do I get emails or phones for Search Contact results?
Waterfall Search Contact returns profiles with email and phone channels redacted. Pass an availablelinkedin_url from a result as linkedin to Contact Enrichment. Set include_phones: true if you also need phone enrichment. Phone enrichment may add charges when numbers are found.
Which API should I use if I only need phone numbers?
Use Phone Enrichment for a known person. It acceptslinkedin, email, full_name + domain, or first_name + last_name + domain and returns available phone numbers in E.164 format. If you also need broader profile data, use Contact Enrichment with include_phones: true.
How is Email Verification different from Contact Enrichment?
Waterfall Email Verification checks an address you already have and returnsvalid, invalid, risky, or unknown. It does not find a person or discover a new email address. Contact Enrichment looks up a person and returns available profile and contact data.
The status fields also differ: Email Verification uses output.email.email_status, while enriched person records use email_verified_status with safe, risky, invalid, unknown, or provider_error. Interpret the field for the endpoint you called.
Can I enrich companies as well as people?
Yes. Waterfall Company Enrichment starts with a domain, company LinkedIn identifier, or company name. It returns available company details such as headcount, industry, location, and description. Prefer a domain or LinkedIn identifier when available, since names can be shared by several businesses. See CRM enrichment for using contact and company data together.Can I find prospects before I have a target account list?
Yes. Waterfall Search Company finds companies by industry, headquarters country, and headcount range. Provide at least one of those filters. Then use a returned company’s domain with Search Contact for profiles or Prospector for contacts with email data. Search Company is in Preview. See account prospecting for the next steps.Does Waterfall automatically monitor job changes?
Waterfall Job Change checks employment when you call it. Your application chooses which contacts to check, when to repeat the check, and what to do with the result. It returnsmoved, left, no_change, or unknown, plus a profile when available. Email and phone channels are redacted from that profile. See job-change workflows.
Do I need a LinkedIn URL to check a job change?
No. You can send aprofessional_email on its own, or a contact_full_name with company_domain. You can also pair company_domain with contact_linkedin, professional_email, or personal_email. A name or personal email alone is not enough. The Job Change input table lists all supported combinations, including those using a company LinkedIn identifier.
Does an unknown job-change result mean the contact still works there?
No.unknown means Job Change could not establish the outcome. Keep the employment check unresolved rather than treating it as no_change. Review any returned profile and the evidence you already have. Retrieving the same job returns its saved result; a later employment check requires a new request.
Data and results
How do I check that a result is the right person or company?
Compare the returned identifiers and profile with independent information about the intended person or company. A person’s LinkedIn profile or a company’s domain provides a more specific comparison than a similar name. Review conflicting details and keep the match unresolved when the evidence is insufficient. The evaluation guide explains how to separate incorrect matches from incomplete profiles.Will every request return a complete profile?
No. Waterfall’s available data depends on the input and the matching record. A returned profile can have missing fields, and a search can return no results. Check the fields your workflow needs before scoring, routing, or updating a record. The evaluation guide shows how to measure useful results separately from match coverage.How fresh is the data?
We verify every email we find in real time, just before delivering the enrichment result. Profiles are typically refreshed in under 14 days, with real-time updates when needed. We compare records across providers to check for conflicting or outdated details, clean and structure the results, and benchmark our providers every quarter. Read the returned email verification status before using an address; a completed check can still have a risky or unresolved result. The profile-update window describes typical behavior, not a guaranteed refresh time for every field. To recheck an address already in your database, use Email Verification.How can I identify companies visiting my website?
Use Waterfall Company Reveal to add company context to website visits. Your integration sends the visitor’s IPv4 address, and Waterfall returns available company details, a result type, and a confidence label. Use an acceptable match to connect the visit to an account and decide what to do next. Some visits will not resolve to a company. The website company identification guide includes a request and the fields to review.Can Company Reveal identify the person visiting my website?
Waterfall Company Reveal accepts an IPv4 address and returns company context when a company match is available. It does not identify an individual visitor or prove their employer. Inspect the result type and confidence before using the company association. See website company identification.How should I compare Waterfall with another data provider?
Start with a sample of records from your real workflow and decide which fields matter. A signup flow might need company and role; a recruitment platform might need work history. Give each provider the same inputs, then compare correct matches, missing fields, freshness, completion time, and actual cost. We can help you design the test and review the results. The evaluation guide provides a practical checklist.Can Waterfall help with records my existing provider could not resolve?
You can use Waterfall as an additional enrichment step for unresolved records that have a supported input. Run that subset through the relevant endpoint and measure newly correct, useful results and their cost. Additional coverage depends on the records; do not count a duplicate profile as a new match. See incremental coverage.Access, usage, and pricing
How do I get an API key and pricing?
API access is available by approval. Enter your work email on the Waterfall website to request a key, or book a call to discuss your workflow and pricing. A member of our team reviews every access request; we aim to reply within a couple of hours. We work with a limited number of customers so we can provide direct support and plan capacity around each team’s needs. Once you have a key, send it in thex-api-key header. Follow Authentication and the Quickstart.
Does my API key enable every capability?
Waterfall API access depends on the features enabled for your key. A valid key can receive a permission error for an unavailable capability, and addinginclude_phones: true requires phone enrichment access. Confirm the capabilities your workflow needs with the Waterfall team, and use the Errors guide to interpret the returned code.
How do I see what a request cost?
Whenoutput.usage is present in a Waterfall result, it reports total_usd, counts and costs by category, and balance_remaining_usd. For an asynchronous job, retrieve the result before reading its cost. Usage Tracking explains the fields. Count each job once when totaling costs; prices in example responses are illustrative, not a price list.
Am I charged when nothing is found?
Waterfall billing rules differ by endpoint. Phone Enrichment charges only when a number is returned. Email Verification does not charge for results whereoutput.email.email_status is unknown. For other operations, follow the endpoint’s billing guidance, your agreed rates, and the result’s usage breakdown. Contact our team to confirm how missing or partial results are charged in your planned workflow.
Can I track usage separately for teams or workflows?
Yes. Use a Waterfall master key to create labeled sub-keys for different integrations. Authenticate Account Reporter with a sub-key to compare itskey_usage with overall account_usage. Product prices are returned only to master-key requests. See API key management for creating keys and managing their request limits.
Can I set a spending cap for an agent?
Set the agent’s authorized budget in your execution workflow. Waterfall’soutput.usage helps you track reported job costs, but a balance snapshot does not reserve money for requests already in flight. A sub-key’s per_interval limits request rate, not dollars spent. See Usage Tracking before designing spending controls for parallel calls.
Can I process a list of records?
Yes. Your integration can process a list through individual Waterfall requests within your account’s rate limits. Contact Enrichment, Company Enrichment, Phone Enrichment, and Email Verification accept one subject per request. Search endpoints have their own result limits or pagination. See CRM enrichment for connecting results to a list of records.Can Waterfall support higher request volumes?
Yes. The default for Prospector, Search, Enrichment, Job Change, and Email Verification is 50 requests per 60 seconds. It is not Waterfall’s maximum capacity: we can support volumes more than 10 times higher with the right account and workflow configuration. Email support@waterfall.io with your APIs and expected volume so we can agree on limits for your setup. Your integration must follow the limits configured for its key.Which endpoints are in Preview?
Search Company and Company Titles are marked Preview in these guides. Their behavior may change; discuss your requirements with our team before using them in a critical workflow. See their endpoint references for supported inputs and results.Building an integration
Can Waterfall help build a custom data pipeline?
Yes. We can help you choose APIs, benchmark the fields your product needs, and build a custom data pipeline. Bring your starting inputs, required outputs, expected volume, and destination, such as a CRM, Snowflake, or a Clay table. Customers work directly with our founders in a dedicated channel to plan the integration and review results.Can Waterfall work with Clay, Freckle, or Deepline?
Yes. Connect Waterfall to Clay, Freckle, or Deepline through an HTTP/API step or integration code to enrich leads, find contacts, and verify emails in your workflows. Requests use your Waterfall API key in thex-api-key header.
For Prospector and contact, phone, or company enrichment, include a webhook_url for a compatible receiver to get the completed result. If your setup cannot receive callbacks, save the returned job_id and retrieve the result through the matching Finder. Use custom_fields to carry your source record ID. Your workflow maps the returned fields and writes them back to the right record.
Which calls return results immediately?
Waterfall Search Contact, Search Company, Company Titles, Company Reveal, Job Change, and Email Verification return results in the response. Prospector, Contact Enrichment, Phone Enrichment, and Company Enrichment return ajob_id; retrieve the completed result through the matching Finder or provide a supported webhook_url. See Choose an API.
A synchronous Contact Enrichment option is also available by arrangement for enterprise customers. Contact our team for access details.
Can I receive enrichment results without polling?
Yes. Waterfall Prospector, Contact Enrichment, Phone Enrichment, and Company Enrichment accept awebhook_url. Waterfall sends the Finder payload to that URL when processing completes. Your integration hosts the receiving endpoint and handles the delivery. Follow Webhook Verification for checking signed deliveries, including the documented behavior when the signature header is absent.
Does a successful HTTP response mean enrichment found a match?
No. A successful Waterfall enrichment launch means the job was accepted. Inspect the job status, completed output, and the fields needed for your task. A completed request can still leave fields unavailable or produce no useful match. The Quickstart and Finder pages explain how to retrieve results.How do I connect enrichment results to my own records?
Usecustom_fields on supported Waterfall requests to pass your CRM record ID, signup ID, or another source label. Waterfall returns that metadata in input.task.custom_fields on job retrieval. Keep the returned job_id with the source record too. See CRM enrichment for an example.