Leads

Update a lead

Update a lead’s fields, tags, custom fields, or status. The email address can only be changed while the lead has not been contacted yet. Reply-based statuses can only be set once the lead has replied.

Requires one of the following scopes: leads:write, leads:all, all:all.

patch/v1/campaigns/{cid}/leads/{leadId}

Request

  • Base URL: https://api.mailbeast.ai
  • URL: https://api.mailbeast.ai/v1/campaigns/{cid}/leads/{leadId}
  • Auth: HTTP bearer

Path parameters

cidstring uuid required
Example:a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60
leadIdstring uuid required
Example:c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37

Headers

Idempotency-Keystring
Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890

Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns 422.

Request body

emailstring

The email can only be changed while the lead has not been contacted yet.

firstNamestring
lastNamestring
companyNamestring
jobTitlestring
websitestring
linkedinProfilestring
locationstring
tagsstring[]
customFieldsobject

Custom fields - each key must be lowercase letters, digits and underscores, starting with a letter, up to 64 characters (e.g. fund_manager); a key outside that form is rejected. The number of fields per campaign is capped, and each value is length-limited.

customFieldLabelsobject

Display labels for custom-field columns (applied on first definition).

customFieldTypesobject

Data types for custom-field columns (text | url | number | date | image; applied on first definition).

status'lead_replied_interested' | 'lead_replied_meeting_request' | 'lead_replied_out_of_office' | 'lead_replied_wrong_person' | 'lead_replied_not_interested' | 'lead_replied_unsubscribed' | 'lead_replied_uncategorized' | 'lead_converted' | 'lead_lost' | 'blacklisted'

Only user-settable statuses are allowed; platform-managed ones such as email_sent or scheduled are rejected. Reply-based statuses (lead_replied_*, lead_converted) require the lead to have already replied. lead_lost and blacklisted can be set at any time.

Example request

{
  "email": "jane.new@acme.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "companyName": "Acme Inc.",
  "jobTitle": "Head of Growth",
  "website": "https://acme.com",
  "linkedinProfile": "https://www.linkedin.com/in/janedoe",
  "location": "Berlin, Germany",
  "tags": [
    "vip",
    "q4"
  ]
}

Response

idstring uuid required
emailstring required
firstNamestring nullable
lastNamestring nullable
companyNamestring nullable
jobTitlestring nullable
websitestring nullable
linkedinProfilestring nullable
locationstring nullable
tagsstring[] required
customFieldsobject required
status'not_contacted' | 'scheduled' | 'email_sent' | 'failed' | 'skipped' | 'lead_replied_interested' | 'lead_replied_meeting_request' | 'lead_replied_out_of_office' | 'lead_replied_bounce' | 'lead_replied_wrong_person' | 'lead_replied_not_interested' | 'lead_replied_unsubscribed' | 'lead_replied_uncategorized' | 'lead_converted' | 'lead_lost' | 'blacklisted' required
providerstring nullable
createdAtstring date-time required
lastContactedAtstring date-time nullable
lastRepliedAtstring date-time nullable
lastOpenedAtstring date-time nullable

Latest of the per-email first opens: when the lead first opened the newest email it opened. Re-opening an email does not move it; null if no email was opened.

lastClickedAtstring date-time nullable

Latest of the per-email first clicks: when the lead first clicked a tracked link in the newest email it clicked. Repeat clicks do not move it; null if no tracked link was clicked.

Example response

{
  "id": "c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37",
  "email": "jane@acme.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "companyName": "Acme Inc",
  "jobTitle": "VP Sales",
  "website": "https://acme.com",
  "linkedinProfile": "https://www.linkedin.com/in/janedoe",
  "location": "New York, US",
  "tags": [
    "vip",
    "q4"
  ],
  "customFields": {
    "industry": "SaaS"
  },
  "status": "not_contacted",
  "verification": {
    "status": "valid",
    "subStatus": "email_ok"
  },
  "provider": "google",
  "metrics": {
    "sent": 2,
    "opened": 1
  },
  "sequenceProgress": {
    "totalSteps": 3,
    "sentCount": 1,
    "plannedCount": 1
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.