Batch Operations

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

Limits

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").

Batch Create

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.

Batch Update

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.

Batch Delete

DELETE /leads/batch

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

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

Webhooks

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.

Tips

• 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.