# Add leads (/api-reference/leads/addLeads)

## Add leads

`POST https://app.alienmail.io/api/v1/campaigns/{id}/leads`

Adds up to 500 people to a campaign by email. In an `active` campaign a new lead's first email is queued at once; in a `draft` or `paused` one they wait as `pending` until it starts. Adding to a `completed` campaign makes it `active` again.

The call is safe to repeat: someone already in the campaign is counted in `alreadyIn` and only their custom values are updated. A person who is already a lead in your workspace keeps the fields stored there; change them with [Update a lead](/api-reference/leads/updateLead). People whose address bounced or who unsubscribed in your workspace are left out and counted.

An entry with an invalid email is reported in `invalid` and the others are still added, so check it. It is refused with 409 when the campaign is `archived`, or `completed` with no connected mailbox or a past end date.

Requires the `LEAD_CAMPAIGN_ENROLL` permission.

Authentication: `Authorization: Bearer <your API key>`

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | integer | yes | The campaign id: the number in the campaign URL in Alienmail, or `id` from the campaign list. An id that is not a campaign of your workspace returns 404. |

### Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `leads` | object[] | yes | 1 to 500 people. When an email appears twice, the first entry is used. |

Example:

```json
{
  "leads": [
    {
      "email": "ada@example.com",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "salutation": "Ms.",
      "jobTitle": "Head of Engineering",
      "department": "Engineering",
      "seniority": "Director",
      "phone": "+44 20 7946 0958",
      "linkedinUrl": "https://www.linkedin.com/in/ada-lovelace",
      "gender": "female",
      "timezone": "Europe/London",
      "language": "en",
      "company": "Analytical Engines",
      "companyDomain": "analyticalengines.com",
      "industry": "Software",
      "companySize": "51-200",
      "revenue": "$10M-$50M",
      "linkedinCompanyUrl": "https://www.linkedin.com/company/analytical-engines",
      "city": "London",
      "state": "England",
      "country": "United Kingdom",
      "countryCode": "GB",
      "description": "Met at the Manchester meetup.",
      "custom": {
        "plan": "pro",
        "renewal_date": "2027-01-04"
      }
    }
  ]
}
```

### Responses

**200**: What happened to the people in the request.

```json
{
  "received": 2,
  "added": 2,
  "reactivated": 0,
  "alreadyIn": 0,
  "skippedBounced": 0,
  "skippedUnsubscribed": 0,
  "invalid": [],
  "ignoredCustomKeys": []
}
```

**400**: The request is invalid: `fields` names the fields to fix. Code `invalid_json` when the body is not valid JSON.

**401**: The API key is missing, wrong or revoked, its creator left the workspace or was suspended, or the workspace is archived or deleted.

**403**: The API key's role lacks the permission this endpoint needs.

**404**: The campaign, lead or mailbox was not found in your workspace.

**409**: The campaign, lead or mailbox is in a state that does not allow this. `message` says why.

**415**: The body is not JSON: send it with `Content-Type: application/json`.

**429**: More than 120 requests in a minute with this key, or a workspace limit on adding and removing leads.

Errors look like `{ "error": { "code": "not_found", "message": "Campaign not found" } }`. See the Errors page.