{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"aaaa3592-c0a9-4acc-bdda-0d80086420ef","name":"Waterfall","description":"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:\n\n#### 1\\. Prospector\n\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.\n\n- **Prospector Launcher:** Start a contact search using a domain name, LinkedIn profile, or company name. Returns a `job_id`.\n    \n- **Prospector Finder:** Retrieve results using the `job_id` from the Prospector Launcher.\n    \n\n#### 2\\. Contact Enrichment\n\nEnrich contact information by inputting professional/personal emails, LinkedIn URL/slug, or name + domain. Get enriched data like verified emails, job titles, and locations.\n\n- **Contact Enrichment Launcher**: Start a contact enrichment process. Returns a `job_id`.\n    \n- **Contact Enrichment Finder**: Retrieve results using the `job_id` from the Contact Enrichment Launcher.\n    \n\n#### 3\\. Company Enrichment\n\nEnrich company data by inputting a domain, LinkedIn URL/slug, or company name. Receive details like headcount, industry, and headquarters.\n\n- **Company Enrichment Launcher**: Start a company search using a domain name, LinkedIn URL/slug, or company name. Returns a `job_id`.\n    \n- **Company Enrichment Finder**: Retrieve results using the `job_id` from the Company Enrichment Launcher.\n    \n\n#### 4\\. Phone Number Enrichment\n\nGet mobile numbers by inputting an email, LinkedIn URL/slug, or name + domain.\n\n- **Phone Enrichment Launcher**: Start a phone number enrichment process. Returns a `job_id`.\n    \n- **Phone Enrichment Finder**: Retrieve results using the `job_id` from the Phone Enrichment Launcher.\n    \n\n#### 5\\. Email Verification\n\nVerify 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.\n\n#### 6\\. Account Reporter\n\nProvides information about your account's usage.\n\n#### 7\\. API Keys Management\n\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.[](https://docs.waterfall.io/waterfall-v1-1)\n\n---\n\n# Authentication\n\nTo access the API, you need the API key provided in your contract. You can ask for multiple API keys for different teams' usage.\n\nAll API request URLs start with [https://api.waterfall.io/v1/](https://api.waterfall.io/v1/). The API key needs to be provided in the header of the request as `x-waterfall-api-key`.\n\n---\n\n# Rate limit\n\nThe 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.\n\n##### X-RateLimit-Limit\n\nThe maximum number of requests you can make per interval. Only sent when the rate limit is reached.\n\n##### X-RateLimit-Interval\n\nThe length of the interval in seconds. Only sent when the rate limit is reached.\n\n##### Retry-After\n\nThe number of seconds to wait until the rate limit window resets. Only sent when the rate limit is reached.\n\n---\n\n# Filters\n\nWaterfall offers three filtering options for prospect requests:\n\n## 1\\. Title Filter\n\nThe `title_filter` parameter allows to request specific titles with each request. How it works:\n\n- If it is present it must not be empty.\n    \n- If it is present and not empty, like `\"title_filter\": \"((accountant) OR (accounting)) AND NOT(intern)\"`, Waterfall will filter employees using that title filter\n    \n- If it is not present, Waterfall will try to use [<code>title_filters</code>](https://docs.waterfall.io/waterfall-v1-1/prospector/prospector-launcher/multiple-title-filters). One of `\"title_filter\"` or `\"title_filters\"` must be present.\n    \n- If neither `title_filters` is present Waterfall will use your existing configured filters. To change your configured filters, contact your account manager.\n    \n\nThe filter can be any Boolean expression. Accepted operators are: AND, OR NOT. Operators must be written with capital letters and separated by spaces.\n\nThere is no need to enclose multi-word titles in parenthesis.\n\nMatching for each title is inclusive. For example:\n\n- `manager` will match `program mamanger`, `senior manager` and `account manager sales`\n    \n- `vp data` will match `vp innovation, data science, co-founder`, `vp information and data` and `vp data science`\n    \n- `head product` will match `global head of product` and `head of product management office`\n    \n- `data lead` will match `lead data scientist`, `data lead engineer`, `data lead` and `data engineering lead`\n    \n\nFew examples of valid filters:\n\n- manager\n    \n- manager AND NOT project manager\n    \n- manager AND NOT (project manager OR sales manager)\n    \n- ( (manager OR director) AND (sales OR marketing) ) AND NOT ( project manager OR sales manager)\n    \n- (accountant OR accounting) AND NOT intern\n    \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) ) )\n    \n\nFew examples of invalid filters:\n\n- `mangerANDdirector`: spaces must be used around operators\n    \n- `manager NOT (project manager)`: invalid boolean expression\n    \n- `(accountant OR accounting AND NOT intern`: missing closing parenthesis before AND\n    \n\nWe recommend using parenthesis to make sure the order of evaluation is what you intend and to make the expression more easy to read.\n\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`\n\nIn 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.\n\nIf you need help with writing title filters, contact your account manager to schedule a call with the support team.\n\n---\n\n## 2\\. Multiple title filters\n\nThe `title_filters` parameter allows requesting multiple title_filters in a specific order. It is used if [<code>title_filter</code>](https://docs.waterfall.io/waterfall-v1-1/prospector/prospector-launcher/title-filter) is not present.\n\nExample:\n\n``` json\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\n ```\n\nWaterfall will try each filter in the order provided up to the requested `limit`.\n\n---\n\n## 3\\. Location filter\n\nThe location-based search is performed using two parameters: `location_country` and `location_name`.\n\n#### Location_country\n\nThe 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](https://waterfall-io-public.s3.amazonaws.com/waterfall_location_country.txt).\n\nAn empty parameter is ignored.\n\n**Location_countries**\n\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:\n\n- \\[\"France\"\\]\n    \n- \\[\"France\", \"Germany\"\\]\n    \n\nFull list of coutries can be found [here](https://waterfall-io-public.s3.us-east-1.amazonaws.com/waterfall_location_country.txt).\n\n#### Location_name\n\nThe `location_name` the parameter represents the location of the contact's current address. Typical locations are:\n\n- `San Francisco, California, United States`\n    \n- `Paris, Ile-De-France, France`\n    \n\nA location comprises a city, region/state, and country. Partial matches are possible. Acceptable partial locations are:\n\n- city, region: `San Francisco, California`, `Paris, Ile-De-France`\n    \n- region, country: `California, United States`, `Ile-De-France, France`\n    \n- city: `San Francisco`, `Paris`\n    \n- region: `California`, `Ile-De-France`\n    \n- country:`United States`, `France`\n    \n\nIn many cases, the best results are obtained using only the region. Region filter tends to match most results.\n\nAn empty parameter is ignored.\n\n---\n\n# Errors\n\nThe waterfall API uses conventional HTTP response codes to indicate the success or failure of a request, with detailed information in case of error.\n\n| **Status Code** | **Description** |\n| --- | --- |\n| 200 OK | The request was successful. |\n| 400 Bad Request | Your request was not valid. |\n| 401 Unauthorized | Missing API key. |\n| 403 Forbidden | Bad API key. |\n| 404 Not Found | The requested endpoint does not exist. |\n| 500 Internal Server Error | Something went wrong on our end. |\n\n---\n\n# Contact Support\n\nContact Support:  \nEmail: [felix@waterfall.io](https://mailto:felix@waterfall.io)","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"41982888","team":6766641,"collectionId":"aaaa3592-c0a9-4acc-bdda-0d80086420ef","publishedId":"2sAYXBGzrT","public":true,"publicUrl":"https://postman.waterfall.io","privateUrl":"https://go.postman.co/documentation/41982888-aaaa3592-c0a9-4acc-bdda-0d80086420ef","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2025-02-14T05:29:24.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/41301bd4870bc5036868322c87af548dd482a00c7f10260cc18b094496c16839","favicon":"https://waterfall.io/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://postman.waterfall.io/view/metadata/2sAYXBGzrT"}