Skip to main content
POST
Create or attach lead

Authorizations

Authorization
string
header
required

Use Authorization: Bearer tc_live_xxxxx

Body

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

E.164, with a length that fits its country code (+2125550100 is refused). An account holds one lead per phone number.

Pattern: ^\+[1-9]\d{8,14}$
list_id
string<uuid>
required
email
string<email>
status
enum<string>
default:New
Available options:
New,
Contacted,
Converted,
Unsubscribed
notes
string
notes_append
string

Not applied on create. Can't be sent with notes.

tags
string[]
metadata
object

Custom fields passed to calls. Platform keys are ignored.

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

Existing lead added to the list

For an existing lead, list_ids shows every list it's in and the request's other fields weren't applied.

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
existed
boolean
required

True when the phone number matched an existing lead (200).

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>[]