Submit Batch
Submit a batch of enrichment items across multiple products in a single API call.
https://api.leadmagic.io/v1/batchTry this endpointOpen the API playground
Endpoint Details
Submit a batch of enrichment items. Unlike Bulk Jobs which run a single product across many rows, the batch API allows mixed-product submissions: each item can use a different product, and can be routed to an external provider you registered.
POST /v1/batch: mixed-product batch. Each item in theitemsarray specifies its ownproduct.POST /v1/:product/batch: single-product batch. Theproductis in the URL path; items do not need to specify a product.
- Pricing
- Rate Limits
| Metric | Value |
|---|---|
| Cost | Billed per successful item, same rate as the matching single-request product |
| Failed Items | FREE: no credits charged for items that fail |
| Queued | No charge to submit; billing accrues as items are processed |
Quick Example
Request Parameters
1–500 items per request. Each item is capped at 64 KiB, and the whole request at 8 MiB.
Optional idempotency key. Submitting the same key twice returns the original batch instead of creating a duplicate.
HTTPS URL to receive a POST when the batch completes or an item fails. SSRF-validated server-side: must resolve to a public IP.
Queue priority: either normal or low. Use low for backfills you don't want competing with live traffic.
Arbitrary metadata stored with the batch and echoed back on status and results.
Associate the whole batch with a client record. See Client Management.
Client name recorded alongside the batch, when you don't have a client_id.
Items whose input.email is on one of your suppression lists are skipped automatically, and identical items in one request are sent once.
Repeats from earlier batches
Set metadata.dedup_mode to choose what happens to an item that already succeeded in a batch in the last 7 days.
dedup_mode | Result |
|---|---|
none (default) | Runs the item again |
soft | Skips the item |
hard | Returns the earlier result |
reject | Refuses the whole batch with 422 |
Response
UUID identifier for the batch. Use this to poll status and fetch results.
Always "accepted" for a freshly submitted batch. Processes asynchronously.
Number of items in the submission.
Example Response
Status Codes
202
Accepted: batch queued for processing
400
Bad Request: malformed body or missing required fields
401
Unauthorized: invalid or missing API key
402
Payment Required: insufficient credits
429
Rate Limit: too many submits; retry after backoff
Best Practices
Use batch for mixed-product enrichment
Use batch for mixed-product enrichment
Need to enrich emails AND find profiles in one call? Submit items with different products in a single batch. Each item's credits are tracked independently.
Specify a provider for waterfall enrichment
Specify a provider for waterfall enrichment
Pass provider: "ext:<providerId>" on an item to route that item through an external enrichment provider instead of LeadMagic's default. See Provider Registry for managing providers.
Use client_id for cost tracking
Use client_id for cost tracking
Associate batches with a client_id to track credits per client. View client-level metrics via Client Metrics.
Register a webhook for async notification
Register a webhook for async notification
Use webhook_url instead of polling for batch completion. The webhook fires on batch.completed, batch.failed, and item.failed events.
Was this page helpful?
We value your feedback.