Bulk Jobs

Submit Bulk Job

Changed on Sep 23, 2026

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

Base URL
https://api.leadmagic.io
Auth
API key in header X-API-Key

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"
}

Changes

Sep 23, 202651db6fceee34 Revision changes
- breaking
  added to the response body oneOf list for the response status
- info
  removed from the response body allOf list for the response status
Aug 25, 20261f289eff3a26 Revision changes
- breaking
  the ////// response's property format changed from uri to uri-reference for status
- breaking
  the ////// response's property format changed from uri to uri-reference for status
- breaking
  the ////// response's property format changed from uri to uri-reference for status
- breaking
  the ////////// response's property format changed from uri to uri-reference for status
- breaking
  the ////////// response's property format changed from uri to uri-reference for status

Operation history