> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kakiyo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Delete Prospects

> Delete multiple prospects in a single operation

## 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

<ParamField body="prospectIds" type="array" required>
  Array of prospect IDs to delete (maximum 100)
</ParamField>

<ParamField body="campaignId" type="string">
  Optional campaign ID to filter prospects (additional safety check)
</ParamField>

## 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

<Warning>
  **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.
</Warning>

## Request Example

```json theme={null}
{
  "prospectIds": [
    "prospect_123",
    "prospect_456", 
    "prospect_789"
  ],
  "campaignId": "campaign_abc"
}
```

## Response Structure

```json theme={null}
{
  "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

```bash theme={null}
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 theme={null}
// 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 theme={null}
# 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

```json theme={null}
{
  "error": "invalid_request",
  "message": "prospectIds array is required and cannot be empty"
}
```

### Too Many Prospects

```json theme={null}
{
  "error": "too_many_prospects",
  "message": "Maximum 100 prospects allowed per request"
}
```

### Campaign Mismatch

```json theme={null}
{
  "error": "campaign_mismatch",
  "message": "Some prospects do not belong to the specified campaign"
}
```

## Batch Processing Strategy

For large-scale deletions, implement batch processing:

```javascript theme={null}
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:

```javascript theme={null}
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:

```json theme={null}
{
  "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

<Info>
  **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
</Info>

## 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


## OpenAPI

````yaml DELETE /prospects
openapi: 3.1.0
info:
  title: Kakiyo API
  description: API for automating LinkedIn outreach campaigns with AI-powered conversations
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.kakiyo.com/v1
security:
  - bearerAuth: []
paths:
  /prospects:
    delete:
      summary: Bulk Delete Prospects
      description: Delete multiple prospects in a single operation
      operationId: bulkDeleteProspects
      requestBody:
        description: Prospect IDs to delete
        content:
          application/json:
            schema:
              type: object
              properties:
                prospectIds:
                  type: array
                  items:
                    type: string
                  maxItems: 100
                  example:
                    - prospect_123
                    - prospect_456
                campaignId:
                  type: string
                  example: campaign_abc
              required:
                - prospectIds
        required: true
      responses:
        '200':
          description: Bulk deletion completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Bulk deletion completed
                  summary:
                    type: object
                    properties:
                      requested:
                        type: integer
                        example: 3
                      successful:
                        type: integer
                        example: 2
                      failed:
                        type: integer
                        example: 1
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          example: validation_error
        message:
          type: string
          example: The request parameters failed validation
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                example: name
              message:
                type: string
                example: The name field is required
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````