Skip to main content
Waterfall Email Finder API

Create Waterfall Email Finder task

post/v1/enrichments/tasks

Authorizations

X-API-Key or Authorizationstringheaderrequired

We recommend sending your Personal API Key in x-api-key. Datablist handles token renewal for you. Optionally, use an access token as Authorization: Bearer <token> if your application manages tokens itself. Send only one credential header.

Authentication options ↗

Find a work email using a person's name and company, or their LinkedIn profile URL.

Public ID: waterfall-email-finder. Get the current definition. You can read it without authentication.

Code examples: See our Waterfall Email Finder API GitHub repository for cURL, Python (Requests or async HTTPX), and TypeScript examples using names, company names or domains, full names, and LinkedIn profile URLs.

Settings​

Choose the inputs you have:

  • Name and company: use sourceKind: "name_company" (default), with firstName, lastName, and companyNameOrDomain. A company domain is usually less ambiguous than a name. To send one fullName instead, set useFullName: true.
  • LinkedIn profile: use sourceKind: "linkedin" with linkedInProfile. Send a public profile URL; Sales Navigator URLs are not supported.

To use your own lookup services, set useCustomAPIKeys: true and add customSequence entries with an allowed provider and its apiKey. Keep those keys private. Custom sequences can also return finderProvider.

sourceKindstring

Choose how to find the email: by using the person's name and company (default), or by LinkedIn URL.

Allowed values: "name_company", "linkedin"
useFullNameboolean

Use one fullName input instead of firstName and lastName.

Enabled when: sourceKind==name_company,false.

useCustomAPIKeysboolean

Use a custom lookup sequence with your own API keys.

Enabled when: sourceKind==name_company,false.

customSequenceobject[]

Lookup services to try, with your API key for each one.

Enabled when: sourceKind==name_company,false&useCustomAPIKeys==true.

minItems: 1
Show child attributes
providerstringrequired
Allowed values: "icypeas", "enrow", "prospeo", "wiza", "findymail", "leadmagic", "trykitt", "enrich_so", "full_enrich"
apiKeystringrequired

API key for this lookup service.

Additional properties are supported.

Additional properties are supported.

Inputs​

Give each input an inputId you can use to match the result to your record. Put the fields below in its data object.

firstNameany

Person's first name. If you only have the full name, enable 'Use Full Name' in the settings.

Enabled when: sourceKind!=linkedin&useFullName==false. Required when enabled.

lastNameany

Person's last name. If you only have the full name, enable 'Use Full Name' in the settings.

Enabled when: sourceKind!=linkedin&useFullName==false. Required when enabled.

fullNameany

Person's full name. In you have the First Name and Last Name, disable 'Use FullName' in the settings.

Enabled when: sourceKind!=linkedin&useFullName==true. Required when enabled.

companyNameOrDomainstring

For best results, provide the company domain or website (e.g. datablists.com).

Enabled when: sourceKind!=linkedin. Required when enabled.

linkedInProfilestring

Public LinkedIn profile URL, such as https://www.linkedin.com/in/example/. Sales Navigator URLs are not supported.

Additional properties are supported.

Credits and limits​

Cost: 25 credits per email found

Credit usage depends on the lookup work performed. Custom provider keys do not imply that every task is free of Datablist charges. Read creditsUsed for actual usage; do not treat creditsPerInput: null as a zero price.

Send 1–10,000 inputs per task, within 16 KiB per input and 10 MiB per request. Tasks can run for up to 24 hours; completed, failed, or stopped tasks are kept for 90 days.

You can set maxCredits to stop starting new work after a credit threshold. Work already underway can still exceed it. Enrichment and source tasks share your account balance and task limits. See limits and errors.

Accepted task​

The API returns 202 Accepted with a task ID. Save it and check links.self every few seconds. Once the task is completed, failed, or stopped, get Waterfall Email Finder task results. The response below is sample data.

Waterfall Email Finder API overview · Shared task reference

Last updated on