---
title: "Submit Bulk Job"
method: POST
path: "/bulk/submit"
tags: ["Bulk Jobs"]
---

# Submit Bulk Job

`POST /bulk/submit`

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.

## Request body

- BulkSubmissionRequest — Request body for submitting a bulk enrichment job via POST /bulk/submit. Provide exactly one of rows, csv, fileUrl, or scrape.
  - `product` string, required — The enrichment product to run on each row (e.g. email_finder, email_validation, mobile_finder, profile_search, company_search).
  - `rows` object[] — 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.
  - `csv` string — Inline CSV string for /bulk/csv (or /bulk/submit).
  - `fileUrl` string, uri — Public HTTPS URL to a remote file (CSV, JSON, JSONL). SSRF-validated server-side.
  - `format` 'csv' | 'json' | 'jsonl' — File format for fileUrl submissions.
  - `scrape` object — Browser-rendering config for /bulk/scrape (or /bulk/submit).
    - `url` string, uri
    - `mode` 'scrape' | 'crawl' | 'content' | 'markdown' | 'links' | 'json' | 'snapshot'
    - `extractPrompt` string
    - `render` boolean
    - `maxPages` integer
    - `maxDepth` integer
  - `inputMapping` object — Optional column mapping from CSV/JSON columns to product input fields.
  - `callback` object — Webhook configuration.
    - `url` string, uri — HTTPS URL to receive a POST on completion/failure. SSRF-validated.
    - `events` string[]
    - `inlineResults` boolean
    - `secret` string
    - `metadata` object
  - `idempotencyKey` string — Optional idempotency key for safe retries.
  - `metadata` object
  - `presetId` string
  - `outputTransform` object
    - `model` string
    - `prompt` string
    - `jsonSchema` unknown
  - `priority` integer
  - `fileName` string

## Response `202`

Bulk job accepted and queued for processing.

- BulkSubmissionResponse — Response for a successful bulk job submission. HTTP 202 Accepted.
  - `jobId` string, uuid, required — UUID identifier for the bulk job.
  - `product` string, required — The enrichment product this job is running.
  - `endpoint` string, nullable
  - `totalRows` integer, required — Total number of rows in the submission.
  - `status` string, required — Always 'uploaded' for a freshly submitted job.
  - `queue` object, required
    - `position` integer
    - `started` boolean
    - `queuedAt` string, date-time
  - `statusUrl` string, uri
  - `streamUrl` string, uri
  - `wsUrl` string
  - `resultsUrl` string, uri
  - `rowsUrl` string, uri
  - `errorsUrl` string, uri
  - `eventsUrl` string, uri
  - `eventsExportUrl` string, uri
  - `logsUrl` string, uri
  - `downloadUrl` string, uri
  - `progressUrl` string, uri
  - `token` string — Progress token for follow-up reads without the API key.
  - `exp` integer — Unix timestamp when the progress token expires.

## Other responses

- `400` — Bad request. The request body failed validation, or a provided URL failed SSRF validation (SSRF_VALIDATION_FAILED).
- `401` — Unauthorized - Authentication failed. **Common causes:** - Missing X-API-Key header - Invalid or expired API key - Malformed API key
- `402` — Payment Required - Insufficient credits for this request. **Action required:** Add credits to your account at https://app.leadmagic.io/settings/billing
- `429` — Too Many Requests - Rate limit exceeded. **Action required:** Check the `Retry-After` header for when to retry. **Headers returned:** - `Retry-After`: Seconds until you can retry - `RateLimit-Limit`: Your limit per minute - `RateLimit-Remaining`: Remaining requests this minute - `RateLimit-Reset`: Seconds until limit resets
- `500` — Internal Server Error - Something went wrong on our end. **Action required:** Wait 30 seconds and retry. If the problem persists, contact support@leadmagic.io

---

[API](https://skmtc.net/leadmagic/apis/leadmagic-api.md) · [All operations](https://skmtc.net/leadmagic/apis/leadmagic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leadmagic/leadmagic-api/revisions/aa19cf9bc46a/schema)