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

# lead_database.search.completed

> Triggered when a Lead Database search completes

This event is triggered when a Lead Database (A-Leads) bulk search finishes processing and all leads are stored in the database.

## When This Event Fires

* A Lead Database search initiated via the API completes
* All leads from the search have been processed and stored
* The search status changes to `completed`

## Payload

```json theme={null}
{
  "eventId": "evt_1708456789123_abc123def",
  "eventType": "lead_database.search.completed",
  "timestamp": "2024-02-24T10:30:00.000Z",
  "workspaceId": "ws_abc123xyz",
  "data": {
    "search_id": "search_abc123",
    "search_name": "Tech Founders Q1 2024",
    "total_leads_found": 150,
    "requested_limit": 200,
    "started_at": "2024-02-24T10:25:00.000Z",
    "completed_at": "2024-02-24T10:30:00.000Z",
    "duration_ms": 300000,
    "filters": {
      "job_titles": ["CEO", "CTO", "Founder"],
      "locations": ["United States", "Canada"],
      "industries": ["Technology", "Software"],
      "company_sizes": ["11-50", "51-200"]
    },
    "leads": [
      {
        "id": "lead_xyz789",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+1-555-123-4567",
        "linkedin_url": "https://www.linkedin.com/in/johndoe",
        "job_title": "CEO",
        "company": "TechCorp Inc",
        "location": "San Francisco, CA",
        "country": "United States",
        "industry": "Technology",
        "seniority": "C-Level",
        "company_linkedin_url": "https://www.linkedin.com/company/techcorp",
        "website": "https://techcorp.com",
        "employees": "51-200"
      }
    ],
    "results_url": "/v1/lead-database/searches/search_abc123/results"
  }
}
```

## Payload Fields

| Field                    | Type   | Description                                  |
| ------------------------ | ------ | -------------------------------------------- |
| `eventId`                | string | Unique event identifier for idempotency      |
| `eventType`              | string | Always `lead_database.search.completed`      |
| `timestamp`              | string | ISO 8601 timestamp when the search completed |
| `workspaceId`            | string | Your workspace ID                            |
| `data.search_id`         | string | Unique identifier for the search             |
| `data.search_name`       | string | Name you provided for the search             |
| `data.total_leads_found` | number | Total number of leads found                  |
| `data.requested_limit`   | number | Maximum leads you requested                  |
| `data.started_at`        | string | When the search started                      |
| `data.completed_at`      | string | When the search completed                    |
| `data.duration_ms`       | number | Processing time in milliseconds              |
| `data.filters`           | object | Filters used for the search                  |
| `data.leads`             | array  | Array of all found leads with full data      |
| `data.results_url`       | string | API endpoint to fetch results                |

### Lead Object Fields

Each lead in the `leads` array contains:

| Field                  | Type   | Description            |
| ---------------------- | ------ | ---------------------- |
| `id`                   | string | Unique lead identifier |
| `first_name`           | string | Lead's first name      |
| `last_name`            | string | Lead's last name       |
| `full_name`            | string | Lead's full name       |
| `email`                | string | Email address          |
| `phone`                | string | Phone number           |
| `linkedin_url`         | string | LinkedIn profile URL   |
| `job_title`            | string | Current job title      |
| `company`              | string | Current company name   |
| `location`             | string | Location               |
| `country`              | string | Country                |
| `industry`             | string | Industry               |
| `seniority`            | string | Seniority level        |
| `company_linkedin_url` | string | Company LinkedIn URL   |
| `website`              | string | Company website        |
| `employees`            | string | Company size           |

## Use Cases

<CardGroup cols={2}>
  <Card title="CRM Import" icon="database">
    Automatically import leads into your CRM when search completes
  </Card>

  <Card title="Campaign Creation" icon="rocket">
    Trigger campaign creation with the found leads
  </Card>

  <Card title="Notifications" icon="bell">
    Alert your team when lead lists are ready
  </Card>

  <Card title="Data Enrichment" icon="sparkles">
    Trigger additional enrichment workflows
  </Card>
</CardGroup>

## Example Handler

```javascript theme={null}
app.post('/webhooks/sendpilot', (req, res) => {
  const event = req.body;
  
  if (event.eventType === 'lead_database.search.completed') {
    const { search_id, search_name, total_leads_found, leads } = event.data;
    
    // Import leads to CRM
    for (const lead of leads) {
      await crm.createLead({
        firstName: lead.first_name,
        lastName: lead.last_name,
        email: lead.email,
        company: lead.company,
        title: lead.job_title,
        linkedinUrl: lead.linkedin_url,
        source: `SendPilot Search: ${search_name}`
      });
    }
    
    // Send notification
    await slack.notify({
      channel: '#lead-generation',
      text: `✅ Lead Database search "${search_name}" completed!\nFound ${total_leads_found} leads.`
    });
    
    console.log(`Search ${search_id} completed with ${total_leads_found} leads`);
  }
  
  res.status(200).send('OK');
});
```

<Note>
  The `leads` array contains all found leads with complete data. For large result sets, consider processing leads asynchronously.
</Note>