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

# Lead Generation

> Generate and manage leads using the IntentGPT Lead Generation API

## Overview

The Lead Generation API provides powerful tools to generate qualified leads based on specific criteria and manage lead lists. This enables you to build targeted prospect lists for your sales and marketing teams.

## Generate Leads

### GET /leadgen

Generate leads based on customizable criteria.

#### Parameters

| Parameter      | Type    | Required | Description                                                |
| -------------- | ------- | -------- | ---------------------------------------------------------- |
| objective      | string  | Yes\*    | Lead generation objective (e.g., "find marketing leaders") |
| website/domain | string  | No       | Company website or domain to filter by                     |
| topic/t        | string  | No       | Topic filter for lead generation                           |
| keyword/k      | string  | No       | Keyword filter for more specific targeting                 |
| limit          | integer | No       | Maximum leads to return (1-1000, default: 10)              |

\*Required when generating new leads. If no objective is provided, falls back to person intent analysis.

#### Example: Generate Marketing Leaders

```bash theme={null}
curl -X GET "https://api.intentgpt.ai/leadgen" \
-H "X-API-Key: your_api_key" \
-G --data-urlencode "objective=find marketing leaders in SaaS companies" \
--data-urlencode "domain=saas" \
--data-urlencode "topic=marketing automation" \
--data-urlencode "limit=50"
```

#### Response

```json theme={null}
{
  "status": "success",
  "objective": "find marketing leaders in SaaS companies",
  "leads": [
    {
      "name": "John Smith",
      "title": "VP of Marketing",
      "company": "TechCorp",
      "email": "john.smith@techcorp.com",
      "linkedin": "https://linkedin.com/in/johnsmith",
      "intent_score": "HOT"
    }
  ],
  "count": 50
}
```

## Lead Lists Management

### Get Lead Lists

#### GET /leadgen/lists

Retrieve existing lead lists, optionally filtered by user or specific list ID.

#### Parameters

| Parameter | Type   | Description               |
| --------- | ------ | ------------------------- |
| user\_id  | string | Filter lists by user ID   |
| list\_id  | string | Get a specific list by ID |

#### Example: Get All Lists

```bash theme={null}
curl -X GET "https://api.intentgpt.ai/leadgen/lists" \
-H "X-API-Key: your_api_key"
```

#### Example: Get Specific List

```bash theme={null}
curl -X GET "https://api.intentgpt.ai/leadgen/lists?list_id=list_abc123" \
-H "X-API-Key: your_api_key"
```

### Create Lead List

#### POST /leadgen/lists

Create a new lead list with optional automatic lead generation.

#### Request Body

```json theme={null}
{
  "name": "Q1 Marketing Prospects",
  "objective": "Find marketing decision makers in mid-market SaaS",
  "domain": "saas",
  "topic": "marketing automation",
  "keyword": "martech",
  "user_id": "user_123",
  "limit": 100,
  "leads": []  // Optional: pre-existing leads to add
}
```

#### Example Request

```bash theme={null}
curl -X POST "https://api.intentgpt.ai/leadgen/lists" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "name": "Marketing Leaders Q1",
  "objective": "Find CMOs and VPs of Marketing",
  "domain": "enterprise-software",
  "limit": 200
}'
```

#### Response

```json theme={null}
{
  "status": "success",
  "message": "Lead list created successfully",
  "lead_list": {
    "list_id": "list_def456",
    "name": "Marketing Leaders Q1",
    "objective": "Find CMOs and VPs of Marketing",
    "created_date": "2024-01-15T10:30:00Z",
    "lead_count": 200
  }
}
```

### Update Lead List

#### PUT /leadgen/lists/{listId}

Update an existing lead list's metadata or leads.

#### Parameters

* `listId` (path) - ID of the lead list to update

#### Request Body

```json theme={null}
{
  "name": "Updated List Name",
  "objective": "Updated objective",
  "domain": "new-domain",
  "topic": "new-topic",
  "keyword": "new-keyword",
  "user_id": "user_123",
  "leads": [
    {
      "name": "Jane Doe",
      "title": "CMO",
      "company": "NewCorp"
    }
  ],
  "replace_leads": true  // If true, replaces all leads. If false, adds to existing
}
```

#### Example Request

```bash theme={null}
curl -X PUT "https://api.intentgpt.ai/leadgen/lists/list_def456" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "name": "Q1 Marketing Prospects - Updated",
  "replace_leads": false,
  "leads": [
    {
      "name": "Sarah Johnson",
      "title": "Director of Marketing",
      "company": "StartupXYZ",
      "email": "sarah@startupxyz.com"
    }
  ]
}'
```

### Delete Lead List

#### DELETE /leadgen/lists/{listId}

Delete a lead list permanently.

#### Parameters

* `listId` (path) - ID of the lead list to delete

#### Example Request

```bash theme={null}
curl -X DELETE "https://api.intentgpt.ai/leadgen/lists/list_def456" \
-H "X-API-Key: your_api_key"
```

#### Response

```json theme={null}
{
  "status": "success",
  "message": "Lead list list_def456 deleted successfully"
}
```

## Error Responses

### Partial Success (207)

When a lead list is created but leads fail to be added:

```json theme={null}
{
  "status": "partial_success",
  "error": "Created list but failed to add leads: Invalid lead data",
  "list_id": "list_ghi789"
}
```

### Not Found (404)

```json theme={null}
{
  "error": "Lead list not found",
  "status": "failed"
}
```

### Bad Request (400)

```json theme={null}
{
  "error": "Missing required fields: name and objective",
  "status": "failed"
}
```

## Best Practices

### Lead Generation Tips

1. **Be Specific with Objectives**: Use detailed objectives like "Find CTOs at Series B SaaS companies" rather than just "find executives"

2. **Use Multiple Filters**: Combine domain, topic, and keyword filters for more targeted results

3. **Start Small**: Begin with smaller limits (10-50) to test your criteria before generating larger lists

4. **Iterate on Criteria**: Refine your search criteria based on the quality of initial results

### List Management

1. **Organize by Campaign**: Create separate lists for different campaigns or time periods

2. **Use Descriptive Names**: Include timeframe, target persona, and purpose in list names

3. **Regular Updates**: Update lists regularly to maintain data freshness

4. **Backup Important Lists**: Export critical lists before making major updates

## Use Cases

### Sales Prospecting

Generate targeted prospect lists for outbound sales campaigns:

```bash theme={null}
curl -X GET "https://api.intentgpt.ai/leadgen" \
-H "X-API-Key: your_api_key" \
-G --data-urlencode "objective=find sales directors at companies showing CRM intent" \
--data-urlencode "topic=CRM" \
--data-urlencode "keyword=salesforce alternative" \
--data-urlencode "limit=100"
```

### Event Marketing

Build attendee lists for webinars or events:

```bash theme={null}
curl -X POST "https://api.intentgpt.ai/leadgen/lists" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "name": "AI Webinar Prospects",
  "objective": "Find IT leaders interested in AI and machine learning",
  "topic": "artificial intelligence",
  "limit": 500
}'
```

### Account-Based Marketing

Create targeted lists for specific accounts:

```bash theme={null}
curl -X GET "https://api.intentgpt.ai/leadgen" \
-H "X-API-Key: your_api_key" \
-G --data-urlencode "objective=find decision makers at Fortune 500 companies" \
--data-urlencode "domain=enterprise" \
--data-urlencode "topic=digital transformation" \
--data-urlencode "limit=200"
```