Skip to content

Batch Operations

Batch endpoints reduce API calls and improve throughput for bulk operations.

Plan Max per batch
Free 100
Pro 500

Exceeding the limit returns 400 Bad Request: the entire request is rejected and no leads are created.

An empty leads or ids array also returns 400 ("leads array is required" / "ids array is required").

POST /leads/batch

Returns 201 Created if all succeed, 207 Multi-Status on partial failure.

207 Multi-Status is not success. At least one lead failed. Always check the errors array even when the status is 207. Entries in created were saved successfully. Do not treat HTTP 207 like a 2xx “all good” in n8n: branch on status and walk the body.

{
"leads": [
{ "name": "Lead 1", "source": "import", "city": "Athens" },
{ "name": "Lead 2", "source": "import", "city": "Berlin" }
]
}

Deduplication runs per item (same logic as single POST /leads). Duplicate merges count as success but do not consume a slot from your plan’s leads limit.

Response:

{
"created": [
{ "index": 0, "id": "cl_...", "created_at": 1703520000 },
{ "index": 1, "id": "cl_existing...", "created_at": 1703510000, "duplicate": true }
],
"errors": [{ "index": 2, "message": "name is required" }],
"total": 3, "success": 2, "failed": 1
}

The duplicate: true field on a created item means the incoming lead was merged into an existing record; no new lead was created.

PUT /leads/batch

Apply the same partial update to multiple leads. Returns 200 OK if every id succeeds, 207 Multi-Status if any fail.

{
"ids": ["cl_aaa...", "cl_bbb...", "cl_ccc..."],
"data": { "source": "Website", "tags": ["reviewed"] }
}

Response shape:

{
"results": [
{ "index": 0, "id": "cl_aaa...", "success": true },
{ "index": 1, "id": "cl_bbb...", "success": false, "message": "conflict: duplicate email or source_id" }
],
"total": 2,
"success": 1,
"failed": 1
}

On 207, walk results[]: successful items were applied; failed ones include a message.

DELETE /leads/batch

Same status rules as batch update: 200 all ok, 207 partial failure with results[].

{ "ids": ["cl_aaa...", "cl_bbb..."] }

For batch update and delete, inspect results[]: only affected leads have success: true. Missing IDs and IDs outside your account both return success: false, message: "not found". The existing HTTP 207 status applies whenever any item fails (including all items). Grouped webhooks include only successful IDs and their actual count; no event is emitted when all items fail.

Batch operations fire a single grouped webhook event instead of one per lead:

Operation Event Payload
Batch create (new inserts) leads.created { ids: [...], count: N }
Batch create (merged duplicates) leads.updated { ids: [...], count: N }
Batch update leads.updated { ids: [...], count: N }
Batch delete leads.deleted { ids: [...], count: N }
Bulk rescore leads.scored { leads: [{id, score}], count: N }

A single POST /leads/batch can emit both leads.created and leads.updated when some items are inserts and others are merges.

Single-lead operations still fire the singular events (lead.created, lead.updated, etc.). A dedup merge on POST /leads fires lead.updated, not lead.created.

  • Treat 207 as partial failure: identify and retry failed entries by index / results[].
  • Items that are deduplicated (merged) count as success with duplicate: true; they don’t fail and don’t consume a leads slot.
  • For very large datasets (10k+ leads), split into multiple batch requests and respect your plan’s rate limits.
  • Send an Idempotency-Key on POST /leads/batch so a retry returns the same 207 or 201 body and writes nothing twice. One key covers the whole batch. → Retries and idempotency