Skip to main content
DELETE
/
prospects
Bulk Delete Prospects
curl --request DELETE \
  --url https://api.kakiyo.com/v1/prospects \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prospectIds": [
    "prospect_123",
    "prospect_456"
  ],
  "campaignId": "campaign_abc"
}
'
{
  "message": "Bulk deletion completed",
  "summary": {
    "requested": 3,
    "successful": 2,
    "failed": 1
  }
}

​
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

​
prospectIds
array
required
Array of prospect IDs to delete (maximum 100)
​
campaignId
string
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

  1. Batch Size: Use 25-50 prospects per batch for optimal performance
  2. Error Handling: Always check individual results for failures
  3. Rate Limiting: Add delays between large batch operations
  4. Data Backup: Export data before bulk deletions
  5. 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

  1. Verify prospect ownership before deletion
  2. Check for active conversations
  3. Confirm campaign association if specified
  4. 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

​
Performance Optimization

For optimal performance:
  • Use appropriate batch sizes (25-50 prospects)
  • Process during off-peak hours
  • Monitor API rate limits
  • Implement exponential backoff for retries

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Prospect IDs to delete

​
prospectIds
string[]
required
Maximum array length: 100
Example:
["prospect_123", "prospect_456"]
​
campaignId
string
Example:

"campaign_abc"

Response

Bulk deletion completed

​
message
string
Example:

"Bulk deletion completed"

​
summary
object