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.

Batch Create

POST /leads/batch

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

207 Multi-Status means at least one lead failed. Always check the errors array even when the status is 207. Entries in created were saved successfully.

{
  "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:

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

Batch Delete

DELETE /leads/batch

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

Webhooks

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

Operation	Event	Payload
Batch create	leads.created	{ 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 }

Single-lead operations still fire the singular events (lead.created, lead.updated, etc.).

Tips

• Use 207 responses to identify and retry failed entries by index.
• 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.