Sign in

v3

latestOpenAPI 3.1.02026-07-318648277.6 KB
Bulk Jobs

Submit Bulk Job

Submit data for bulk enrichment. Provide exactly one of rows (JSON array), csv (string), fileUrl (HTTPS URL), or scrape (browser rendering config). The job is processed asynchronously; use the returned jobId to poll status via GET /bulk/jobs/{jobId}. Security: fileUrl and callback.url are SSRF-validated server-side. Private/internal IP ranges, localhost, cloud metadata endpoints (169.254.169.254), and non-HTTPS protocols are rejected.

post/bulk/submit

Request body

productstring required

The enrichment product to run on each row (e.g. email_finder, email_validation, mobile_finder, profile_search, company_search).

rowsobject[]

JSON array of row objects for /bulk/json (or /bulk/submit auto-detect). Each row is an object whose keys match the input fields the selected product expects.

csvstring

Inline CSV string for /bulk/csv (or /bulk/submit).

fileUrlstring uri

Public HTTPS URL to a remote file (CSV, JSON, JSONL). SSRF-validated server-side.

format'csv' | 'json' | 'jsonl'

File format for fileUrl submissions.

inputMappingobject

Optional column mapping from CSV/JSON columns to product input fields.

idempotencyKeystring

Optional idempotency key for safe retries.

metadataobject
presetIdstring
priorityinteger
fileNamestring

Example request

{
  "product": "email_finder",
  "outputTransform": {
    "model": "llama-3.1-8b-instruct"
  }
}

Response

Bulk job accepted and queued for processing.

jobIdstring uuid required

UUID identifier for the bulk job.

productstring required

The enrichment product this job is running.

endpointstring nullable
totalRowsinteger required

Total number of rows in the submission.

statusstring required

Always 'uploaded' for a freshly submitted job.

statusUrlstring uri
streamUrlstring uri
wsUrlstring
resultsUrlstring uri
rowsUrlstring uri
errorsUrlstring uri
eventsUrlstring uri
eventsExportUrlstring uri
logsUrlstring uri
downloadUrlstring uri
progressUrlstring uri
tokenstring

Progress token for follow-up reads without the API key.

expinteger

Unix timestamp when the progress token expires.

Example response

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "uploaded"
}