Overview
Delete multiple prospects in a single operation. This endpoint efficiently processes bulk deletions with detailed results for each prospect. Maximum 100 prospects per request. This action cannot be undone.
Request Body
Array of prospect IDs to delete (maximum 100)
Optional campaign ID to filter prospects (additional safety check)
Use Cases
- Campaign Cleanup: Remove multiple invalid prospects
- Data Migration: Clean up prospects during system migrations
- Compliance: Bulk removal for GDPR/privacy requests
- Quality Control: Remove prospects that don’t meet updated criteria
Important Considerations
Permanent Bulk Deletion: This operation permanently deletes ALL specified prospects and their associated data:
- All prospect profiles and contact information
- All conversation histories and messages
- All scheduled tasks and follow-ups
- All analytics data for these prospects
- All webhook events related to these prospects
This action cannot be undone. Process deletions in smaller batches for better control. Request Example
{
"prospectIds": [
"prospect_123",
"prospect_456",
"prospect_789"
],
"campaignId": "campaign_abc"
}
Response Structure
{
"message": "Bulk deletion completed",
"summary": {
"requested": 3,
"successful": 2,
"failed": 1,
"processedAt": "2024-01-20T15:30:00Z"
},
"results": [
{
"prospectId": "prospect_123",
"status": "success",
"prospectName": "John Smith",
"deletedItems": {
"chats": 1,
"messages": 5,
"tasks": 2,
"webhookEvents": 1
}
},
{
"prospectId": "prospect_456",
"status": "success",
"prospectName": "Jane Doe",
"deletedItems": {
"chats": 1,
"messages": 8,
"tasks": 3,
"webhookEvents": 2
}
},
{
"prospectId": "prospect_789",
"status": "failed",
"error": "not_found",
"message": "Prospect not found"
}
],
"campaignStatsUpdated": {
"campaignId": "campaign_abc",
"prospectsCount": 147,
"messagesCount": 407,
"qualifiedCount": 11
}
}
Testing Example
curl -X DELETE "https://api.kakiyo.com/v1/prospects" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prospectIds": ["prospect_123", "prospect_456", "prospect_789"],
"campaignId": "campaign_abc"
}'
// JavaScript/Node.js
const bulkDeleteProspects = async (prospectIds, campaignId = null) => {
const requestBody = { prospectIds };
if (campaignId) {
requestBody.campaignId = campaignId;
}
const response = await fetch('https://api.kakiyo.com/v1/prospects', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify(requestBody)
});
return await response.json();
};
// Usage example
const result = await bulkDeleteProspects([
'prospect_123',
'prospect_456',
'prospect_789'
], 'campaign_abc');
console.log('Bulk Deletion Result:', result);
# Python
import requests
def bulk_delete_prospects(prospect_ids, campaign_id=None):
"""Delete multiple prospects in bulk"""
data = {'prospectIds': prospect_ids}
if campaign_id:
data['campaignId'] = campaign_id
response = requests.delete(
'https://api.kakiyo.com/v1/prospects',
json=data,
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
)
return response.json()
# Usage example
result = bulk_delete_prospects([
'prospect_123',
'prospect_456',
'prospect_789'
], 'campaign_abc')
print('Bulk Deletion Result:', result)
Error Responses
Invalid Request
{
"error": "invalid_request",
"message": "prospectIds array is required and cannot be empty"
}
Too Many Prospects
{
"error": "too_many_prospects",
"message": "Maximum 100 prospects allowed per request"
}
Campaign Mismatch
{
"error": "campaign_mismatch",
"message": "Some prospects do not belong to the specified campaign"
}
Batch Processing Strategy
For large-scale deletions, implement batch processing:
const deleteProspectsInBatches = async (allProspectIds, batchSize = 50) => {
const results = [];
for (let i = 0; i < allProspectIds.length; i += batchSize) {
const batch = allProspectIds.slice(i, i + batchSize);
try {
const result = await bulkDeleteProspects(batch);
results.push(result);
// Add delay between batches to avoid rate limiting
await new Promise(resolve => setTimeout(resolve, 1000));
} catch (error) {
console.error(`Batch ${i / batchSize + 1} failed:`, error);
results.push({ error: error.message, batch });
}
}
return results;
};
Result Analysis
Analyze bulk deletion results:
const analyzeBulkDeletionResults = (results) => {
const analysis = {
totalRequested: 0,
totalSuccessful: 0,
totalFailed: 0,
errors: {},
deletedItems: {
chats: 0,
messages: 0,
tasks: 0,
webhookEvents: 0
}
};
results.forEach(result => {
analysis.totalRequested += result.summary.requested;
analysis.totalSuccessful += result.summary.successful;
analysis.totalFailed += result.summary.failed;
result.results.forEach(item => {
if (item.status === 'success') {
Object.keys(item.deletedItems).forEach(key => {
analysis.deletedItems[key] += item.deletedItems[key];
});
} else {
analysis.errors[item.error] = (analysis.errors[item.error] || 0) + 1;
}
});
});
return analysis;
};
Best Practices
- Batch Size: Use 25-50 prospects per batch for optimal performance
- Error Handling: Always check individual results for failures
- Rate Limiting: Add delays between large batch operations
- Data Backup: Export data before bulk deletions
- Progress Tracking: Implement progress indicators for large operations
Safety Measures
Campaign Filtering
Use campaignId parameter as an additional safety check:
{
"prospectIds": ["prospect_123", "prospect_456"],
"campaignId": "campaign_abc"
}
Validation Steps
- Verify prospect ownership before deletion
- Check for active conversations
- Confirm campaign association if specified
- Validate prospect existence
Recovery Considerations
No Recovery Available: Bulk deleted prospects cannot be recovered. For large operations:
- Test with small batches first
- Keep detailed logs of deletions
- Export critical data before deletion
- Consider implementing soft deletes in your application
- Use appropriate batch sizes (25-50 prospects)
- Process during off-peak hours
- Monitor API rate limits
- Implement exponential backoff for retries
