Skip to main content
PATCH
Update lead

Authorizations

Authorization
string
header
required

Use Authorization: Bearer tc_live_xxxxx

Path Parameters

id
string<uuid>
required

Body

application/json
name
string
Minimum string length: 1
phone_number
string

E.164, with a length that fits its country code. Returns 409 if another lead in the account has it.

Pattern: ^\+[1-9]\d{8,14}$
email
string<email> | null
status
enum<string>

Setting Converted stamps converted_at the first time.

Available options:
New,
Contacted,
Converted,
Unsubscribed
notes
string | null
notes_append
string

Added after the current notes with a blank line between. Can't be sent with notes.

tags
string[]
metadata
object

Replaces all stored custom fields.

us_dnc_declaration
boolean

Required, and must be true, when the request holds any +1 (US) phone number. You confirm that each +1 number has given prior express written consent to be called, or was checked against the National Do Not Call Registry in the last 31 days, and that you keep proof of it. Each accepted request stores this declaration (version us-dnc-2026-11-17) against your API key. Requests without +1 numbers don't need it.

Response

OK

id
string<uuid>
required
account_id
string<uuid>
required
name
string
required
phone_number
string
required
Pattern: ^\+[1-9]\d{8,14}$
status
enum<string>
required
Available options:
New,
Contacted,
Converted,
Unsubscribed
tags
string[]
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
email
string<email> | null
notes
string | null
metadata
object

Custom fields passed to calls as lead context. The platform keys direction, _is_test, _browser_test and _sip_username are stored but never reach a call.

converted_at
string<date-time> | null
list_ids
string<uuid>[]