Skip to main content
Enrichments

Waterfall Email Finder

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.

Outputs​

Each result contains your inputId, a status, the data in outputs, and creditsUsed. If the input failed, error explains why; otherwise it is null.

The fields below depend on your settings and the data found. Results can include fields not yet listed in the catalog.

emailFoundstringrequired

Email Found

format: "email"
emailStatusstring

Deliverability info for found email ('verified', 'unverified'). 'not_found' message when no email has been found. 'missing_source_data', 'invalid_data' for error in input data.

mxProviderstring

Email Provider. One of amazon, apple, barracuda, cisco, csc, gandi, google, ionos, microsoft, mimecast, other, ovh, proofpoint, safenames

finderProviderstring

Which Email Finder provider returned the result.

Enabled when: sourceKind!=linkedin&useCustomAPIKeys==true.

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 and results​

The API returns 202 Accepted with a task ID. Save it, then check links.self every few seconds. Once status is completed, failed, or stopped, read links.results. Failed and stopped tasks can still have useful results. See the task reference.

Example results (sample data and credit amounts):

json
{
  "taskId": "00000000000040008000000000000001",
  "results": [
    {
      "inputId": "row-1",
      "status": "success",
      "outputs": {
        "emailFound": "jane.doe@example.com",
        "emailStatus": "verified"
      },
      "creditsUsed": "1",
      "error": null
    }
  ],
  "nextCursor": null
}

If nextCursor is not null, pass it unchanged in the next request to get more results. Pages default to 50 results; limit accepts 1–100. A page is at most 128 KiB, so it may contain fewer results than requested.