Skip to main content
PATCH
Update Lead
Tags are the wiring. A goal bot wakes on the tags in its includeTags, so adding a tag here is how you put a lead in front of a bot from a script. See PATCH /api/goal-bots/{id}.
Send only the fields you want to change. Anything you leave out is untouched.

Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

Path parameter

string
required
The lead id. A malformed id returns 400 Invalid lead id.

Request body

Exactly seven fields are writable. Anything else in the body is ignored — including phone, which is set when the lead is created and cannot be changed here.
string[]
Replaces the whole tag array — send the complete set, not a delta. Values are trimmed, de-duplicated, and blanks are dropped. Maximum 50 tags.A non-array returns 400 tags must be an array of strings; more than 50 returns 400 A lead can carry at most 50 tags.
string
First name. Trimmed. Pass null to clear it to an empty string.
string
Last name. Trimmed. Pass null to clear it.
string
Email address. Trimmed. Pass null to clear it.
string
Company name. Trimmed. Pass null to clear it.
string
Free-text notes about the lead. Trimmed. Pass null to clear it.Not inert — your bots read this. A task agent sees it through get_lead_details, and campaign personalization can reference it, so anything you write here can end up shaping a reply.
object
Replaces the whole custom-field object. Pass null to clear it to {}. An array or a non-object returns 400 customFields must be an object.Read the keys already in use with GET /api/leads/custom-field-keys.
A body with none of these six fields returns 400 — there is nothing to update. An empty object {} counts as nothing.

Example — tag a lead so a bot picks it up

Example — update details

Success (200 OK)

Returns the full updated lead — the same shape as GET /api/leads/{id}.

Errors