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

# Lead lists add to campaign

## POST /api/v1/public/lead-lists/:id/add-to-campaign/

Add prospects from a lead list to a campaign using their prospect IDs. This allows you to move prospects from a lead list directly into a campaign for outreach.

Auth: `X-API-Key`

### Path Parameters

* `id` (integer, required): Lead list ID (the source lead list containing the prospects)

### Request Body

```json theme={null}
{
  "campaign": 456,
  "prospect_ids": [1001, 1002, 1003, 1004, 1005],
  "allow_duplicates": false,
  "prospects_per_company": 1,
  "activate": true
}
```

### Request Body Parameters

* `campaign` (integer, **required**): The target campaign ID to add prospects to
* `prospect_ids` (array of integers, optional): Array of prospect IDs from the lead list to add to the campaign. If empty or omitted, will add prospects based on `amount` parameter. Defaults to `[]`
* `amount` (integer, optional): Number of prospects to add if `prospect_ids` is empty. Defaults to `0` (which means all matching prospects)
* `allow_duplicates` (boolean, optional): Whether to allow adding prospects that are already in other campaigns. Defaults to `false`
* `prospects_per_company` (integer, optional): Maximum number of prospects per company to add. Useful for limiting multiple contacts from the same company. Defaults to `1`
* `filters` (object, optional): Additional filters to apply when selecting prospects. Defaults to `{}`
* `sort_field` (string, optional): Field to sort prospects by. Defaults to `"id"`
* `sort_direction` (string, optional): Sort direction - `"asc"` or `"desc"`. Defaults to `"asc"`
* `activate` (boolean, optional): If `true` and the campaign is ACTIVE, immediately schedule these prospects for outreach. Defaults to `false`

**Note:** Only the `campaign` field is required. All other fields are optional and will use sensible defaults if not provided.

### Response

```json theme={null}
{
  "success": true,
  "count": 5,
  "prospects": [
    {
      "id": 1001,
      "first_name": "John",
      "last_name": "Doe",
      "job_title": "CEO",
      "email": "john.doe@techcorp.com",
      "phone_number": "+1-555-0123",
      "company": {
        "id": 501,
        "name": "TechCorp Inc",
        "website_url": "https://techcorp.com",
        "industry": "Technology"
      },
      "status": "IN_REVIEW",
      "campaign_id": 456
    }
  ]
}
```

### Response Fields

* `success` (boolean): Whether the operation was successful
* `count` (integer): Number of prospects successfully added to the campaign
* `prospects` (array): Array of prospect objects that were added (includes full prospect details)
* `warning` (string, optional): Warning message if activation was requested but couldn't be completed (e.g., campaign is in DRAFT status)

### Error Responses

#### 400 Bad Request

```json theme={null}
{
  "error": "Missing required fields: campaign, prospect_ids"
}
```

#### 404 Not Found

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

```json theme={null}
{
  "error": "Campaign not found"
}
```

### Workflow Example

This endpoint is useful for the following workflow:

1. Create a lead list
2. Search for prospects and add them to the lead list
3. Optionally enrich the prospects in the lead list
4. **Use this endpoint** to move selected prospects from the lead list to a campaign
5. Campaign is ready to launch with those prospects

### Example Usage

#### Minimal Request (Just Campaign ID)

The simplest possible request - only `campaign` is required:

```bash theme={null}
curl -X POST "https://api.seleqt.ai/api/v1/public/lead-lists/123/add-to-campaign/" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": 456
  }'
```

This will add prospects from lead list 123 to campaign 456 using all default settings.

#### Add Specific Prospects by ID

```bash theme={null}
curl -X POST "https://api.seleqt.ai/api/v1/public/lead-lists/123/add-to-campaign/" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": 456,
    "prospect_ids": [1001, 1002, 1003, 1004, 1005],
    "allow_duplicates": false,
    "prospects_per_company": 1,
    "activate": true
  }'
```

#### Add First N Prospects from Lead List

```bash theme={null}
curl -X POST "https://api.seleqt.ai/api/v1/public/lead-lists/123/add-to-campaign/" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign": 456,
    "prospect_ids": [],
    "amount": 10,
    "allow_duplicates": false,
    "prospects_per_company": 2
  }'
```

### Python Example

```python theme={null}
import requests

API_KEY = "<your-api-key>"
BASE_URL = "https://api.seleqt.ai/api/v1"

# Step 1: Get prospects from your lead list
lead_list_response = requests.get(
    f"{BASE_URL}/public/lead-lists/123/leads/",
    headers={"X-API-Key": API_KEY}
)
prospects = lead_list_response.json()["prospects"]

# Step 2: Extract prospect IDs you want to add (e.g., first 5)
prospect_ids = [p["id"] for p in prospects[:5]]

# Step 3: Add those prospects to a campaign
response = requests.post(
    f"{BASE_URL}/public/lead-lists/123/add-to-campaign/",
    headers={"X-API-Key": API_KEY},
    json={
        "campaign": 456,
        "prospect_ids": prospect_ids,
        "allow_duplicates": False,
        "prospects_per_company": 1,
        "activate": True
    }
)

result = response.json()
print(f"Added {result['count']} prospects to campaign!")
```

### JavaScript Example

```javascript theme={null}
const API_KEY = '<your-api-key>';
const BASE_URL = 'https://api.seleqt.ai/api/v1';

async function addProspectsToCampaign() {
  // Step 1: Get prospects from lead list
  const leadListResponse = await fetch(
    `${BASE_URL}/public/lead-lists/123/leads/`,
    {
      headers: {
        'X-API-Key': API_KEY
      }
    }
  );
  const leadList = await leadListResponse.json();

  // Step 2: Extract prospect IDs
  const prospectIds = leadList.prospects.slice(0, 5).map(p => p.id);

  // Step 3: Add to campaign
  const response = await fetch(
    `${BASE_URL}/public/lead-lists/123/add-to-campaign/`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        campaign: 456,
        prospect_ids: prospectIds,
        allow_duplicates: false,
        prospects_per_company: 1,
        activate: true
      })
    }
  );

  const result = await response.json();
  console.log(`Added ${result.count} prospects to campaign!`);
}

addProspectsToCampaign();
```

### Notes

* Prospects can only be in one campaign at a time. When you add a prospect to a campaign, they are moved from their current location (lead list or previous campaign)
* If `allow_duplicates` is `false`, the endpoint will skip prospects that are already in other campaigns
* The `prospects_per_company` parameter helps you limit the number of contacts from the same company, which is useful for avoiding over-contacting a single organization
* Setting `activate: true` will immediately schedule the prospects for outreach if the campaign status is ACTIVE. If the campaign is DRAFT or PAUSED, the prospects will be added but not scheduled
* If the lead list doesn't have enough prospects to fulfill the `amount` requested, all available prospects will be added