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

# Add Leads to Campaign

> Adds one or more leads to a campaign for calling.

# Add Leads to a Campaign

Adds one or more leads to a campaign for calling. If a lead with the same phone or email already exists, it will be linked to the campaign. Otherwise, a new lead is created automatically.

This is the primary endpoint for **Clay**, **Zapier**, and other automation tool integrations.

## Request

`POST /v1/campaigns/:id/leads`

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | uuid | Yes | The campaign ID to add leads to |

### Body Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `leads` | array | Yes | Array of lead objects to add |
| `leads[].phone` | string | Conditional | Phone in E.164 format (required if no email or lead\_id) |
| `leads[].email` | string | Conditional | Email address (required if no phone or lead\_id) |
| `leads[].lead_id` | uuid | Conditional | Existing lead ID (use if lead already exists) |
| `leads[].first_name` | string | No | First name |
| `leads[].last_name` | string | No | Last name |
| `leads[].company_name` | string | No | Company name |
| `leads[].title` | string | No | Job title |
| `leads[].linkedin_url` | string | No | LinkedIn profile URL |

> [!NOTE]
>
> Each lead in the array must include at least one of: `phone`, `email`, or `lead_id`. The API automatically deduplicates leads based on phone number or email within your workspace.

## Example

```bash cURL theme={null}
curl -X POST \
  "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/campaigns/c1d2e3f4-.../leads" \
  -H "Authorization: Bearer rchd_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {
        "first_name": "Marie",
        "last_name": "Dupont",
        "phone": "+33698765432",
        "company_name": "TechCo",
        "title": "Head of Sales"
      },
      {
        "first_name": "Pierre",
        "last_name": "Martin",
        "phone": "+33612345678",
        "email": "pierre@startup.io"
      }
    ]
  }'
```

```javascript JavaScript theme={null}
const campaignId = "c1d2e3f4-...";
const response = await fetch(
  `https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/campaigns/${campaignId}/leads`,
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer rchd_live_xxxxxxxxxxxx",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      leads: [
        {
          first_name: "Marie",
          last_name: "Dupont",
          phone: "+33698765432",
          company_name: "TechCo",
          title: "Head of Sales"
        },
        {
          first_name: "Pierre",
          last_name: "Martin",
          phone: "+33612345678",
          email: "pierre@startup.io"
        }
      ]
    })
  }
);
const data = await response.json();
```

```python Python theme={null}
import requests

campaign_id = "c1d2e3f4-..."
response = requests.post(
    f"https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/campaigns/{campaign_id}/leads",
    headers={
        "Authorization": "Bearer rchd_live_xxxxxxxxxxxx",
        "Content-Type": "application/json"
    },
    json={
        "leads": [
            {
                "first_name": "Marie",
                "last_name": "Dupont",
                "phone": "+33698765432",
                "company_name": "TechCo",
                "title": "Head of Sales"
            },
            {
                "first_name": "Pierre",
                "last_name": "Martin",
                "phone": "+33612345678",
                "email": "pierre@startup.io"
            }
        ]
    }
)
data = response.json()
```

## Response

```json theme={null}
{
  "data": {
    "campaign_id": "c1d2e3f4-...",
    "results": [
      {
        "lead_id": "new-lead-uuid-1",
        "status": "added"
      },
      {
        "lead_id": "existing-lead-uuid",
        "status": "already_in_campaign"
      }
    ]
  }
}
```

### Result Statuses

| Status | Description |
| - | - |
| `added` | Lead was successfully added to the campaign |
| `already_in_campaign` | Lead was already in the campaign (no duplicate created) |

> [!WARNING]
>
> If a lead object is missing all three identifiers (`phone`, `email`, `lead_id`), it will be skipped and an error will be returned in the results array for that entry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.