On this page

PATCH/campaigns/:campaignId/leads/:leadId

Update CRM fields on a lead. 0 credits. Rate class: patch_lead. Body must include at least one of tag, excluded, or a CRM/profile field below.

Request

PATCH /campaigns/search-xyz/leads/lead_abc
X-API-Key: sk_live_...
Content-Type: application/json

{
  "tag": "Interested",
  "excluded": false,
  "custom1": "VIP",
  "custom10": "Q4"
}

Field	Notes
`tag`	`null` / `""` clears; else one of the writable tags below
`excluded`	boolean
Profile / CRM	Optional — see below. `null` clears a slot (stored empty; echoed as `null`)

Writable `tag` values

Built-ins (case-insensitive, stored as canonical labels): Interested, Not interested, Wrong person, Meeting booked, Resolved.

Also accepts active custom reply tags from GET /tags. Classifier alias Meeting request is not assignable — use Meeting booked. Archived custom tags are rejected.

GET ?tag= filters may still accept additional list-only labels; write paths use the catalog above.

Profile & CRM merge fields

Optional keys (strings; unknown keys → 400). Not email or linkedinUrl.

Keys	Max
`fullName`, `firstName`, `lastName`	120
`companyName`	200
`website`, `companyLinkedin`	500
`jobTitle`	400
`phone`	80
`headline`	500
`location`, `companySize`, `companyCountry`, `companyCity`	120
`personalization`, `custom`, `custom1` … `custom10`	2000

If you patch firstName / lastName without fullName, the API recomputes fullName from the new parts plus any existing name fields.

Response

{
  "id": "lead_abc",
  "tag": "Interested",
  "excluded": false,
  "fields": {
    "custom1": "VIP",
    "custom10": "Q4"
  }
}

fields is present only when CRM/profile keys were written in this request (cleared slots echo as null).

Errors

Error code	When
`validation_error`	Empty body / unknown fields / invalid tag / oversize CRM
`not_found`	Unknown campaign or lead

Prefer POST …/leads/batch-update when tagging/excluding/CRM-updating many leads (max 100, 0 credits, 6/min).
Auto-exclude tags on batch-update apply immediately (no polite-ack defer) — differs from this PATCH / inbox path.
Permanent removal: POST …/leads/batch-delete (irreversible, no refund).
List excluded leads: GET …/leads?excluded=true.
Detail (includes CRM slots): GET …/leads/:id.

MCP

Tool: update_lead.