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

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

## Example

<CodeGroup>
  ```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()
  ```
</CodeGroup>

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