Bulk Delete Prospects

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

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

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

Show child attributes

Documentation Index

​Overview

​Request Body

​Use Cases

​Important Considerations

​Request Example

​Response Structure

​Testing Example

​Error Responses

​Invalid Request

​Too Many Prospects

​Campaign Mismatch

​Batch Processing Strategy

​Result Analysis

​Best Practices

​Safety Measures

​Campaign Filtering

​Validation Steps

​Recovery Considerations

​Performance Optimization

Authorizations

Body

Response

Overview

Request Body

Use Cases

Important Considerations

Request Example

Response Structure

Testing Example

Error Responses

Invalid Request

Too Many Prospects

Campaign Mismatch

Batch Processing Strategy

Result Analysis

Best Practices

Safety Measures

Campaign Filtering

Validation Steps

Recovery Considerations

Performance Optimization