Tasks

Create an asynchronous enrichment task

Start an enrichment task with settings and input rows. The API returns 202 Accepted with a task ID; the work runs in the background. Save the ID to check status and read results.

Choose a uniqueId that no active source or enrichment task in your account is using. An active duplicate returns 409 DuplicateApiTask. Once a task finishes or becomes overdue, reusing its ID starts new work and can charge credits again.

Your account has a target limit of 20 active tasks. Simultaneous requests can occasionally exceed it. For input and request sizes, see limits and errors.

If creation returns 503 ApiTaskDispatchFailed or the response is lost, check task history before retrying. Some work may already have run. See safe retries.

Required permissions: enrichments:tasks:create

post/v1/enrichments/tasks

Authorizations

Authorizationstringheaderrequired

Use an account access token as Bearer <token>.

Get an access token ↗

Body

application/json · required

Additional properties are not allowed.

enrichmentIdstringrequired

An authorized enrichment ID from catalog discovery.

uniqueIdstringrequired

pattern: "^[A-Za-z0-9_-]+$"minLength: 1maxLength: 128

settingsobject

Validated against the requested enrichment's settingsSchema from catalog discovery.

Show child attributes

object

Validated against the requested enrichment's settingsSchema from catalog discovery.

Additional properties are supported.

inputsobject[]required

minItems: 1maxItems: 10000

Show child attributes

Additional properties are not allowed.

inputIdstringrequired

Your ID for this input. Returned unchanged so you can match results to your records.

minLength: 1maxLength: 128

dataobjectrequired

Show child attributes

object

Additional properties are supported.

maxCreditsstring

Stop starting new work after this credit threshold. Work already underway can exceed it. Omit for no task-specific limit; your account balance still applies. "0" stops after the first paid completion. Values round upward to hundredth-credit precision. Read credits.used for actual usage.

pattern: "^[0-9]+(\\.[0-9]+)?$"

Response

202409413422429503

New task stored durably and all queue batches accepted

202 · application/json

@idstringrequired

@typestringrequired

const: "EnrichmentTask"

enrichmentIdstringrequired

uniqueIdstringrequired

pattern: "^[A-Za-z0-9_-]+$"minLength: 1maxLength: 128

statusstringrequired

The task is active while queued, running, or stop_asked. Read results after completed, failed, or stopped. Reaching maxCredits can finish with partial results. A stop ends in stopped unless the task also fails.

Allowed values: "queued", "running", "stop_asked", "completed", "failed", "stopped"

errorobject | nullrequired

Null while the task is active or successfully completed. On failure, includes error details and a traceId when available. A stopped task can keep an error that occurred before it stopped.

Show child attributes

reasonstringrequired

Stable reason for a failed task.

Allowed values: "dispatch_failed", "deadline_exceeded", "worker_failed", "enrichment_failed", "credits_error"

codestringrequired

messagestringrequired

traceIdstring | nullrequired

createdAtstringrequired

format: "date-time"

startedAtstring | nullrequired

format: "date-time"

finishedAtstring | nullrequired

format: "date-time"

progressobjectrequired

Show child attributes

totalInputsintegerrequired

minimum: 1maximum: 10000

finishedInputsintegerrequired

minimum: 0maximum: 10000

outcomesobjectrequired

Show child attributes

successintegerrequired

minimum: 0

noResultintegerrequired

minimum: 0

errorintegerrequired

minimum: 0

skippedintegerrequired

minimum: 0

creditsobjectrequired

Show child attributes

usedstringrequired

pattern: "^[0-9]+(\\.[0-9]+)?$"

maxstring | nullrequired

Null when the caller omitted maxCredits (no limit).

pattern: "^[0-9]+(\\.[0-9]+)?$"

linksobjectrequired

Show child attributes

object

Additional properties are supported.

kindstringrequired

const: "enrichment"

Create an asynchronous enrichment task

PythoncURLJavaScriptPHPGo

import requests

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

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

payload = {
    "enrichmentId": "name_to_domain",
    "uniqueId": "company-import-20261009-part-1",
    "settings": {},
    "inputs": [{
        "inputId": "company-123",
        "data": {
            "companyName": "Acme, Inc."
        }
    }, {
        "inputId": "company-456",
        "data": {
            "companyName": "Example GmbH"
        }
    }]
}

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

print(response.text)

Response · illustrative example

202409413422429503

{
  "@id": "string",
  "@type": "EnrichmentTask",
  "enrichmentId": "string",
  "uniqueId": "string",
  "status": "queued",
  "error": {
    "reason": "dispatch_failed",
    "code": "string",
    "message": "string",
    "traceId": "string"
  },
  "createdAt": "2024-07-29T15:51:28.071Z",
  "startedAt": "2024-07-29T15:51:28.071Z",
  "finishedAt": "2024-07-29T15:51:28.071Z",
  "progress": {
    "totalInputs": 0,
    "finishedInputs": 0
  },
  "outcomes": {
    "success": 0,
    "noResult": 0,
    "error": 0,
    "skipped": 0
  },
  "credits": {
    "used": "string",
    "max": "string"
  },
  "links": {},
  "kind": "enrichment"
}