# Update a lead (/api-reference/leads/updateLead)

## Update a lead

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

Changes a lead's fields and custom values, and stops or resumes emails to them. Only what you send changes.

Fields and custom values can be edited while the campaign is `draft` or `paused`, and in an `active` campaign until the lead has been sent an email. Otherwise the call returns 409: pause the campaign first.

`status: "stopped"` stops emails to an `active` or `pending` lead; they stay in the campaign. `status: "active"` resumes a `stopped` lead with their next email. Other changes of status return 409, as does any status change in an `archived` campaign.

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. |
| `email` | path | string | yes | The lead email address. Encode it for a URL (`@` as `%40`). Upper and lower case are treated the same. |

### Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `firstName` | string \| null | no | First name. Up to 191 characters. `null` or an empty string clears it. |
| `lastName` | string \| null | no | Last name. Up to 191 characters. `null` or an empty string clears it. |
| `salutation` | string \| null | no | How to address them, like `Dr.` or `Ms.`. Up to 191 characters. `null` or an empty string clears it. |
| `jobTitle` | string \| null | no | Job title. Up to 191 characters. `null` or an empty string clears it. |
| `department` | string \| null | no | Department. Up to 191 characters. `null` or an empty string clears it. |
| `seniority` | string \| null | no | Seniority level. Up to 191 characters. `null` or an empty string clears it. |
| `phone` | string \| null | no | Phone number, in any format. Up to 191 characters. `null` or an empty string clears it. |
| `linkedinUrl` | string \| null | no | LinkedIn profile URL. Up to 191 characters. `null` or an empty string clears it. |
| `gender` | string \| null | no | Gender. Up to 191 characters. `null` or an empty string clears it. |
| `timezone` | string \| null | no | Time zone. Up to 191 characters. `null` or an empty string clears it. |
| `language` | string \| null | no | Language. Up to 191 characters. `null` or an empty string clears it. |
| `company` | string \| null | no | Company name. Up to 191 characters. `null` or an empty string clears it. |
| `companyDomain` | string \| null | no | Company website domain. Up to 191 characters. `null` or an empty string clears it. |
| `industry` | string \| null | no | Industry. Up to 191 characters. `null` or an empty string clears it. |
| `companySize` | string \| null | no | Company size, as text. Up to 191 characters. `null` or an empty string clears it. |
| `revenue` | string \| null | no | Company revenue, as text. Up to 191 characters. `null` or an empty string clears it. |
| `linkedinCompanyUrl` | string \| null | no | LinkedIn company page URL. Up to 191 characters. `null` or an empty string clears it. |
| `city` | string \| null | no | City. Up to 191 characters. `null` or an empty string clears it. |
| `state` | string \| null | no | State or region. Up to 191 characters. `null` or an empty string clears it. |
| `country` | string \| null | no | Country. Up to 191 characters. `null` or an empty string clears it. |
| `countryCode` | string \| null | no | Country code. Up to 191 characters. `null` or an empty string clears it. |
| `description` | string \| null | no | Notes about this person. Up to 5000 characters; only your workspace sees them. `null` or an empty string clears it. |
| `custom` | object | no | Custom values to change. Each key must already be a custom column of the campaign. `null` or an empty string clears a value; keys you leave out are kept. |
| `status` | "active" \| "stopped" | no | `stopped` stops emails to this lead; they stay in the campaign. `active` resumes a stopped lead. |

Example:

```json
{
  "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": "enterprise"
  },
  "status": "stopped"
}
```

### Responses

**200**: The updated lead.

```json
{
  "email": "ada@example.com",
  "status": "active",
  "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"
  },
  "lastSentAt": "2026-11-13T09:30:00.000Z",
  "addedAt": "2026-11-13T09:30:00.000Z",
  "updatedAt": "2026-11-13T09:30:00.000Z"
}
```

**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.