Tasks

Create a task

POST/api/open/v1/tasksCreate a screening task

Creating a task charges your balance and starts execution immediately. You are billed for the effective count after normalisation, de-duplication and country filtering.

Fields

Field	Type		Description
type	integer	required	Product ID, from the /products endpoint
file_path	string	required	The file_path returned by the upload-url endpoint
file_name	string	required	Original file name, used for display and result naming
country	string	optional	ISO2 country code. Required for phone products (see country_required in /products); not used for email or username products
description	string	optional	Task note; defaults to the file name
follow_up_types	integer[]	optional	Ordered product IDs for the follow-up chain; each step is charged separately
notifications	object[]	optional	Completion notifications, e.g. [{"channel":"email","lang":"en"}]

Example request body

{
  "type": 19,
  "file_path": "portal/upload/1/20260918/ab12cd_numbers.txt",
  "file_name": "numbers.txt",
  "country": "US"
}

Fields that are not accepted

The count is computed server-side from the actual file, and the billing key is determined by the signature. These fields are ignored if sent.

Field	Type	Description
line_count	—	The count is computed server-side from the file; a declared value never affects billing
api_key_id	—	The billing key is determined by the key used to sign the request

Query tasks

GET/api/open/v1/tasksList tasks

GET/api/open/v1/tasks/{id}Task detail (poll for completion)

Poll the task detail endpoint to learn when it is complete, then fetch results.

Response fields

Field	Type	Description
id	integer	Task ID, used for polling and for fetching results
status	integer	Task status; see the table below
type	integer	The public product ID
country	string	ISO-2 country code; email and username tasks report "N/A"
file_name	string	The original file name submitted at creation
total	integer	The number actually charged for: the effective count after normalisation, de-duplication and country filtering, usually fewer than the file's line count
success	integer	Rows processed so far; use it to estimate progress
activated	integer	Rows that matched (activated / registered) — the result count that matters
cost	integer	Amount charged, in micro-USD (1 USD = 1,000,000). An integer, to avoid floating-point error
created_at	integer	Creation time, Unix seconds
finished_at	integer	Completion time, Unix seconds; 0 means not finished
error_code	string	A stable error code when the task failed; empty when there is none
parent_task_id	integer	Points at the previous task in a follow-up chain; 0 for a task that was not derived

status values

Poll the task until it reaches a terminal state: 6 means complete with results ready, 8 means it failed and was refunded. Everything else is in progress — keep waiting.

1CreatedCreated, waiting to be queued

2PendingQueued

3ProcessingScreening in progress

4ProcessedScreening done, results being assembled

5ExportingExporting results

6ExportedComplete; results are downloadableterminal

7UnknownUnknown state; retry later

8ErrorFailed — see error_code. Failed tasks are refundedterminal

Follow-up chain

Optional. Each step automatically creates the next task using the previous step's effective results, charging for each. The chain stops silently if results are insufficient or the balance runs out.

{ "type": 19, "follow_up_types": [22, 31], "...": "..." }