Batch Operations

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

⚠️ Deduplication is not included in batch create POST /leads/batch skips duplicate detection for performance. If you need deduplication, use single POST /leads calls, or pre-deduplicate your dataset before importing.

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" }
  ]
}

Response:

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

Batch Update

PUT /leads/batch

Apply the same partial update to multiple leads:

{
  "ids": ["cl_aaa...", "cl_bbb...", "cl_ccc..."],
  "data": { "category": "Restaurant", "tags": ["reviewed"] }
}

Batch Delete

DELETE /leads/batch

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

Tips

• Use 207 responses to identify and retry failed entries by index.
• For very large datasets (10k+ leads), split into multiple batch requests and respect your plan’s rate limits.