Clay logo

LeadMagic has made more than one billion API calls with Clay and won The Unstoppable Wheel award.

Recap
LeadMagicDocs

Submit Batch

Submit a batch of enrichment items across multiple products in a single API call.

POSThttps://api.leadmagic.io/v1/batch
Try 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 the items array specifies its own product.
  • POST /v1/:product/batch: single-product batch. The product is in the URL path; items do not need to specify a product.
MetricValue
CostBilled per successful item, same rate as the matching single-request product
Failed ItemsFREE: no credits charged for items that fail
QueuedNo charge to submit; billing accrues as items are processed

Quick Example


Request Parameters

items
array
required

1–500 items per request. Each item is capped at 64 KiB, and the whole request at 8 MiB.

idempotencyKey
string

Optional idempotency key. Submitting the same key twice returns the original batch instead of creating a duplicate.

webhook_url
string

HTTPS URL to receive a POST when the batch completes or an item fails. SSRF-validated server-side: must resolve to a public IP.

priority
string
default"normal"

Queue priority: either normal or low. Use low for backfills you don't want competing with live traffic.

metadata
object

Arbitrary metadata stored with the batch and echoed back on status and results.

client_id
string

Associate the whole batch with a client record. See Client Management.

client_name
string

Client name recorded alongside the batch, when you don't have a client_id.

budget_user_id
string

Ignored. Member budgets always apply to the member whose API key sends the request.

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_modeResult
none (default)Runs the item again
softSkips the item
hardReturns the earlier result
rejectRefuses the whole batch with 422

Response

batchId
string

UUID identifier for the batch. Use this to poll status and fetch results.

status
string

Always "accepted" for a freshly submitted batch. Processes asynchronously.

items_count
integer

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

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.

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.

Associate batches with a client_id to track credits per client. View client-level metrics via Client Metrics.

Use webhook_url instead of polling for batch completion. The webhook fires on batch.completed, batch.failed, and item.failed events.