Create Waterfall Email Finder task

post/v1/enrichments/tasks

Authorizations

Authorizationstringheaderrequired

Use an account access token as Bearer <token>.

Get an access token ↗

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.

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 overview · Shared task reference

Request

PythoncURLJavaScriptPHPGo

import requests

url = "https://api.datablist.com/v1/enrichments/tasks"

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

payload = {
    "enrichmentId": "waterfall-email-finder",
    "uniqueId": "waterfall-email-finder-example",
    "settings": {
        "sourceKind": "name_company"
    },
    "inputs": [{
        "inputId": "row-1",
        "data": {
            "firstName": "Jane",
            "lastName": "Doe",
            "companyNameOrDomain": "example.com"
        }
    }]
}

response = requests.post(url, headers=headers, json=payload)

print(response.text)

Response · illustrative example

202

{
  "@id": "00000000000040008000000000000001",
  "@type": "EnrichmentTask",
  "kind": "enrichment",
  "enrichmentId": "waterfall-email-finder",
  "uniqueId": "waterfall-email-finder-example",
  "status": "queued",
  "createdAt": "2026-10-09T10:00:00Z",
  "startedAt": null,
  "finishedAt": null,
  "progress": {
    "totalInputs": 1,
    "finishedInputs": 0
  },
  "credits": {
    "used": "0",
    "max": null
  },
  "error": null,
  "links": {
    "self": "https://api.datablist.com/v1/enrichments/tasks/00000000000040008000000000000001",
    "results": "https://api.datablist.com/v1/enrichments/tasks/00000000000040008000000000000001/results",
    "inputs": "https://api.datablist.com/v1/enrichments/tasks/00000000000040008000000000000001/inputs"
  },
  "outcomes": {
    "success": 0,
    "noResult": 0,
    "error": 0,
    "skipped": 0
  }
}