Download Results

GET/v1/tasks/{token}/result

Once result_available is true, this returns the download URL for the result file together with the final counts. Files are retained for 7 days by default, controlled by the platform’s result_retention_days setting.

Response Example

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "submitted": 5000,
    "prefiltered": 0,
    "deduped": 0,
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0,
    "unknown_processed": 0,
    "unknown_unprocessed": 0
  }
}

Response fields

Field	Type	Description
task_id	string	The task token, echoed back.
download_url	string (URL)	Where the result file lives. Requires the same API key as every other call.
expires_at	string (ISO 8601) | null	When the file stops being downloadable.
summary.submitted	integer	Rows received in the submission.
summary.prefiltered	integer	Rows dropped before detection.
summary.deduped	integer	Duplicate rows removed.
summary.total	integer	Rows actually checked.
summary.valid	integer	Rows confirmed as registered.
summary.invalid	integer	Rows confirmed as not registered.
summary.unknown	integer	Rows the provider could not resolve.
summary.unknown_processed	integer	Unknown rows that were retried and settled.
summary.unknown_unprocessed	integer	Unknown rows still unresolved, and refunded.

Download before expires_at

The URL is not permanent. Once the retention window closes the file is deleted and both the URL and the download endpoint return 404 result_expired.

Download the file

GET/v1/tasks/{token}/download

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/download" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -o result.zip

This endpoint streams a file rather than JSON: application/zip, or text/csv when the task produced a single result. It returns 404 when the task is not found, has expired, or belongs to another account, and 422 result_not_ready when the task has not finished.

download_url and this endpoint are interchangeable — the URL exists so a browser or a worker can fetch the file without constructing the path.

Next

• Bulk examples — the whole submit → poll → download cycle in one script