{ "openapi": "3.0.1", "info": { "title": "Waterfall Contact Enrichment API - Email and Mobile Finder", "description": "Find work emails, personal emails and mobile numbers for B2B contacts from a profile URL or a name and company, with every address verified. Also reverse email lookup, and people and company search across job title, seniority, industry, headcount and tenure. Pay per result.", "version": "0.1", "x-build-id": "XCjf8qHHnJ2eNga60" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~waterfall-contact-enrichment-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-waterfall-contact-enrichment-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/nabeelbaghoor~waterfall-contact-enrichment-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-waterfall-contact-enrichment-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/nabeelbaghoor~waterfall-contact-enrichment-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-waterfall-contact-enrichment-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "What to do", "enum": [ "enrich", "reverse", "searchPeople", "searchCompanies", "lookupPerson", "lookupCompany" ], "type": "string", "description": "Enrich finds contact details for people you already know of. Reverse lookup turns an email address back into the person and company behind it. The two searches find new people or companies from filters, and return profiles without contact details. The two lookups return the single best match for one identifier.", "default": "enrich" }, "linkedinUrls": { "title": "Professional network profile URLs", "type": "array", "description": "In enrich mode, the profiles to find contact details for, one per line. This is the highest-yielding input this provider takes: a profile URL raises the email hit rate by up to a fifth and the mobile number hit rate by up to three fifths against a name and company alone, and it is also what makes the full profile come back with the result.", "items": { "type": "string" } }, "contacts": { "title": "Contacts to enrich", "type": "array", "description": "In enrich mode, contacts given as fields rather than as a URL. Each entry is an object with first_name, last_name and either domain or company_name, and optionally linkedin_url and a custom object of your own reference values. Use this when you have CRM rows rather than profile links. Entries missing a name or a company are refused here rather than charged for." }, "emails": { "title": "Email addresses", "type": "array", "description": "In reverse lookup mode, the addresses to identify, one per line. Each one comes back with the person and the company behind it, where the provider can resolve them.", "items": { "type": "string" } }, "enrichFields": { "title": "What to find", "type": "array", "description": "In enrich mode, which contact details to look for. This is what a run costs on your own plan: a work email is 1 credit, a personal email 3, and a mobile number 10. Leaving this empty looks for the work email alone, because asking for all three costs fourteen times as much and that should be a decision rather than a default.", "items": { "type": "string", "enum": [ "contact.work_emails", "contact.personal_emails", "contact.phones" ], "enumTitles": [ "Work email (1 credit per contact found)", "Personal email (3 credits per contact found)", "Mobile phone number (10 credits per contact found)" ] }, "default": [ "contact.work_emails" ] }, "currentJobTitles": { "title": "Current job titles", "type": "array", "description": "In people search mode, filter on current job titles. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. Job titles to match at the person current employer, for example Head of Sales or VP Engineering.", "items": { "type": "string" } }, "seniorityLevels": { "title": "Seniority levels", "type": "array", "description": "In people search mode, filter on how senior the person is in their current role. Several levels are combined as alternatives.", "items": { "type": "string", "enum": [ "Owner", "Founder", "C-level", "Partner", "VP", "Head", "Director", "Manager", "Senior" ], "enumTitles": [ "Owner", "Founder", "C-level", "Partner", "VP", "Head", "Director", "Manager", "Senior" ] }, "default": [] }, "jobFunctions": { "title": "Job functions", "type": "array", "description": "In people search mode, filter on the broad function the person works in. Pair it with the sub function field for something narrower.", "items": { "type": "string", "enum": [ "Administrative", "Agriculture & Environment", "Construction & Trades", "Consulting & Advisory", "Customer Service", "Design", "Education", "Energy & Utilities", "Entertainment & Gaming", "Executive & Leadership", "Finance", "Hospitality & Tourism", "Human Resources", "Legal", "Marketing", "Media & Communications", "Medical & Health", "Non-Profit & Government", "Not Employed", "Operations", "Personal & Home Services", "Product", "Project & Program Management", "Public Safety & Security", "Research & Science", "Retail & Consumer", "Sales", "Software", "Traditional Engineering", "Transportation & Logistics" ], "enumTitles": [ "Administrative", "Agriculture & Environment", "Construction & Trades", "Consulting & Advisory", "Customer Service", "Design", "Education", "Energy & Utilities", "Entertainment & Gaming", "Executive & Leadership", "Finance", "Hospitality & Tourism", "Human Resources", "Legal", "Marketing", "Media & Communications", "Medical & Health", "Non-Profit & Government", "Not Employed", "Operations", "Personal & Home Services", "Product", "Project & Program Management", "Public Safety & Security", "Research & Science", "Retail & Consumer", "Sales", "Software", "Traditional Engineering", "Transportation & Logistics" ] }, "default": [] }, "subFunctions": { "title": "Job sub functions", "type": "array", "description": "In people search mode, filter on job sub functions. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. The narrower function under the one above, for example Data Entry, Field Sales or Backend Engineering.", "items": { "type": "string" } }, "pastJobTitles": { "title": "Past job titles", "type": "array", "description": "In people search mode, filter on past job titles. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. Titles the person held before their current role. This is how you find people who have done a job before, rather than people doing it now.", "items": { "type": "string" } }, "personNames": { "title": "Person names", "type": "array", "description": "In people search mode, filter on person names. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. A first name, last name or full name.", "items": { "type": "string" } }, "personLinkedinUrls": { "title": "Person profile URLs", "type": "array", "description": "In people search mode, filter on person profile urls. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. Professional network profile URLs for specific people.", "items": { "type": "string" } }, "personLocations": { "title": "Person locations", "type": "array", "description": "In people search mode, filter on person locations. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. A continent, country, region or city. The country goes in English and the region and city in the local language, which is how this provider stores them.", "items": { "type": "string" } }, "personLanguages": { "title": "Languages spoken", "type": "array", "description": "In people search mode, filter on languages spoken. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it.", "items": { "type": "string" } }, "personSkills": { "title": "Skills", "type": "array", "description": "In people search mode, filter on skills. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. Listed skills, for example Python, Kubernetes or Contract Negotiation.", "items": { "type": "string" } }, "personUniversities": { "title": "Universities attended", "type": "array", "description": "In people search mode, filter on universities attended. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it.", "items": { "type": "string" } }, "currentCompanyNames": { "title": "Current company names", "type": "array", "description": "In people search mode, filter on current company names. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it.", "items": { "type": "string" } }, "currentCompanyDomains": { "title": "Current company domains", "type": "array", "description": "In people search mode, filter on current company domains. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. Company website domains, for example example.com. Turn on exact matching for these.", "items": { "type": "string" } }, "currentCompanyLinkedinUrls": { "title": "Current company profile URLs", "type": "array", "description": "In people search mode, filter on current company profile urls. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it.", "items": { "type": "string" } }, "currentCompanyIndustries": { "title": "Current company industries", "type": "array", "description": "In people search mode, filter on current company industries. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. One of the provider industry names, for example Software Development or Hospitals and Health Care.", "items": { "type": "string" } }, "currentCompanySpecialties": { "title": "Current company specialties", "type": "array", "description": "In people search mode, filter on current company specialties. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it.", "items": { "type": "string" } }, "currentCompanyTypes": { "title": "Current company types", "type": "array", "description": "In people search mode, filter on what kind of organisation the employer is.", "items": { "type": "string", "enum": [ "Partnership", "Nonprofit", "Educational", "Privately Held", "Public Company", "Self-Owned", "Self-Employed", "Government Agency" ], "enumTitles": [ "Partnership", "Nonprofit", "Educational", "Privately Held", "Public Company", "Self-Owned", "Self-Employed", "Government Agency" ] }, "default": [] }, "currentCompanyHeadquarters": { "title": "Current company headquarters", "type": "array", "description": "In people search mode, filter on current company headquarters. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. Where the employer is based, as a city, region or country.", "items": { "type": "string" } }, "pastCompanyNames": { "title": "Past company names", "type": "array", "description": "In people search mode, filter on past company names. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. Employers the person worked at before. Useful for alumni targeting.", "items": { "type": "string" } }, "pastCompanyDomains": { "title": "Past company domains", "type": "array", "description": "In people search mode, filter on past company domains. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it.", "items": { "type": "string" } }, "companyNames": { "title": "Company names", "type": "array", "description": "In company search mode, filter on company names. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it.", "items": { "type": "string" } }, "companyDomains": { "title": "Company domains", "type": "array", "description": "In company search mode, filter on company domains. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. Website domains, for example example.com. Turn on exact matching for these.", "items": { "type": "string" } }, "companyLinkedinUrls": { "title": "Company profile URLs", "type": "array", "description": "In company search mode, filter on company profile urls. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it.", "items": { "type": "string" } }, "companyKeywords": { "title": "Description keywords", "type": "array", "description": "In company search mode, filter on description keywords. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. Words that appear in the company description. This is the filter that finds companies doing a thing rather than companies filed under a category.", "items": { "type": "string" } }, "companySpecialties": { "title": "Company specialties", "type": "array", "description": "In company search mode, filter on company specialties. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it.", "items": { "type": "string" } }, "companyIndustries": { "title": "Company industries", "type": "array", "description": "In company search mode, filter on company industries. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. One of the provider industry names, for example Software Development or Hospitals and Health Care.", "items": { "type": "string" } }, "companyHeadquarters": { "title": "Headquarters locations", "type": "array", "description": "In company search mode, filter on headquarters locations. One value per line. Put a minus sign in front of a line to exclude it instead of requiring it. A city, region or country.", "items": { "type": "string" } }, "companyTypes": { "title": "Company types", "type": "array", "description": "In company search mode, filter on what kind of organisation it is.", "items": { "type": "string", "enum": [ "Partnership", "Nonprofit", "Educational", "Privately Held", "Public Company", "Self-Owned", "Self-Employed", "Government Agency" ], "enumTitles": [ "Partnership", "Nonprofit", "Educational", "Privately Held", "Public Company", "Self-Owned", "Self-Employed", "Government Agency" ] }, "default": [] }, "exactMatch": { "title": "Match values exactly", "type": "boolean", "description": "Require every text filter to match exactly rather than approximately. Matching is never case sensitive either way. Off is right for company and job titles, where the provider tolerates missing words, extra words and reordering. On is right for domains and profile URLs, where an approximate match is meaningless.", "default": false }, "headcountMin": { "title": "Minimum headcount", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Smallest employee count to include, on the current employer in people search and on the company itself in company search. Leave at zero for no lower bound.", "default": 0 }, "headcountMax": { "title": "Maximum headcount", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Largest employee count to include. Leave at zero for no upper bound.", "default": 0 }, "foundedYearMin": { "title": "Founded no earlier than", "minimum": 0, "maximum": 2100, "type": "integer", "description": "Earliest founding year to include. Set this alone to find younger companies.", "default": 0 }, "foundedYearMax": { "title": "Founded no later than", "minimum": 0, "maximum": 2100, "type": "integer", "description": "Latest founding year to include.", "default": 0 }, "yearsInPositionMin": { "title": "Minimum years in current role", "minimum": 0, "maximum": 60, "type": "integer", "description": "People search only. Filter on how long the person has held their current title. A low maximum here finds people newly promoted into a buying role.", "default": 0 }, "yearsInPositionMax": { "title": "Maximum years in current role", "minimum": 0, "maximum": 60, "type": "integer", "description": "People search only. Leave at zero for no upper bound.", "default": 0 }, "yearsAtCompanyMin": { "title": "Minimum years at current company", "minimum": 0, "maximum": 60, "type": "integer", "description": "People search only. Tenure at the employer rather than in the role, which are different numbers for anyone promoted internally.", "default": 0 }, "yearsAtCompanyMax": { "title": "Maximum years at current company", "minimum": 0, "maximum": 60, "type": "integer", "description": "People search only. Leave at zero for no upper bound.", "default": 0 }, "daysSinceJobChangeMin": { "title": "Minimum days since job change", "minimum": 0, "maximum": 20000, "type": "integer", "description": "People search only. Leave at zero for no lower bound.", "default": 0 }, "daysSinceJobChangeMax": { "title": "Maximum days since job change", "minimum": 0, "maximum": 20000, "type": "integer", "description": "People search only. Set this to ninety to find people who started somewhere new in the last quarter, which is the window in which they are still choosing their own tools.", "default": 0 }, "requireWorkEmail": { "title": "Keep only rows with a work email", "type": "boolean", "description": "Drop enriched contacts where no work email was found. Note that a contact with a mobile number and no email is still a usable contact, so this is a narrower filter than it looks.", "default": false }, "requirePhone": { "title": "Keep only rows with a phone number", "type": "boolean", "description": "Drop enriched contacts where no mobile number was found. Only does anything when mobile numbers were among the details asked for.", "default": false }, "requireAnyContact": { "title": "Keep only rows with some contact detail", "type": "boolean", "description": "Drop enriched contacts where nothing at all was found, keeping anyone reachable by any route. Usually the right switch rather than the two above.", "default": false }, "workEmailStatuses": { "title": "Keep only these work email statuses", "type": "array", "description": "The provider verifies every address it returns and reports how confident it is. Deliverable bounces about two percent of the time and high probability about nine. Catch-all is higher again, and invalid is excluded from the best-address column already. Leave empty to keep every status.", "items": { "type": "string", "enum": [ "DELIVERABLE", "HIGH_PROBABILITY", "CATCH_All", "INVALID" ], "enumTitles": [ "Deliverable: verified, roughly a 2 percent bounce rate", "High probability: catch-all but likely valid, roughly 9 percent", "Catch-all: unverifiable, a higher bounce rate again", "Invalid: very likely to bounce" ] }, "default": [] }, "minCompanyHeadcount": { "title": "Minimum company headcount in the result", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Drop rows whose company is smaller than this, after the fact. Different from the headcount range above, which is asked of the provider: this one also applies to enrichment results, where there is no search filter to use.", "default": 0 }, "jobName": { "title": "Job name", "type": "string", "description": "A label for this batch on your provider dashboard, so you can find it later. A person name works well when enriching one contact." }, "reportCredits": { "title": "Report your provider balance", "type": "boolean", "description": "Log how many credits your provider workspace has left before the run starts. Informational only, and a failure to read it does not stop the run.", "default": false }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 60, "type": "integer", "description": "Pace the run under the provider limit of 60 requests a minute across all endpoints. The default sits just under it rather than on it, because a burst that lands on the boundary is refused rather than queued.", "default": 55 }, "jobTimeoutMinutes": { "title": "Batch timeout in minutes", "minimum": 1, "maximum": 720, "type": "integer", "description": "Give up waiting for one enrichment batch after this long. The batch keeps running at the provider and its results stay available there, so nothing is lost. Waterfall enrichment queries a series of upstream sources in turn, so a full batch genuinely takes minutes rather than seconds.", "default": 20 }, "skipNotFound": { "title": "Skip values with no result", "type": "boolean", "description": "Leave contacts the provider found nothing for, and inputs refused before they were sent, out of the dataset. Off by default, because knowing which of your contacts could not be resolved is usually the point. Misses are never charged for either way.", "default": false }, "maxResults": { "title": "Maximum results", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Stop after this many rows. Enrichment batches are submitted one at a time, so this caps what you spend on your own provider plan as well as what you spend here.", "default": 100 }, "apiKey": { "title": "API key", "type": "string", "description": "Your own API key for the contact enrichment API, taken from the API page of your provider dashboard. Stored as a secret and never logged." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }