Create Waterfall Phone Finder task

post/v1/enrichments/tasks

Authorizations

Authorizationstringheaderrequired

Use an account access token as Bearer <token>.

Get an access token ↗

Send a public LinkedIn profile URL to find a phone number. Sales Navigator URLs are not supported.

Public ID: waterfall-phone-finder. Get the current definition. You can read it without authentication. Check availability in the catalog.

Settings

Use cacheAge to select the allowed cache age; the default is 30 days. To use your own provider keys, enable useCustomAPIKeys and supply a customSequence with a supported provider and its apiKey. Keep credentials private. The finderProvider output is described with an enableOnSetting condition for custom sequences.

cacheAgestring

Maximum age of a cached result you will accept. Defaults to 30 days.

Allowed values: "30", "61", "183", "0"

useCustomAPIKeysboolean

Use a custom lookup sequence with your own API keys.

customSequenceobject[]

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

Enabled when: useCustomAPIKeys==true.

minItems: 1

Show child attributes

providerstringrequired

Allowed values: "enrow", "prospeo", "findymail", "wiza", "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 profileUrl in its data object.

profileUrlstringrequired

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: 500 credits per phone number found

The standard price is 500 credits per phone number found. Searches without a result and accepted cached results are not charged. Custom provider sequences can change Datablist usage. creditsPerInput: null describes variable usage, not a free task.

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 Phone Finder task results. The response below is sample data.

Waterfall Phone 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-phone-finder",
    "uniqueId": "waterfall-phone-finder-example",
    "settings": {},
    "inputs": [{
        "inputId": "row-1",
        "data": {
            "profileUrl": "https://www.linkedin.com/in/example-person"
        }
    }]
}

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

print(response.text)

Response · illustrative example

202

{
  "@id": "00000000000040008000000000000001",
  "@type": "EnrichmentTask",
  "kind": "enrichment",
  "enrichmentId": "waterfall-phone-finder",
  "uniqueId": "waterfall-phone-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
  }
}