Skip to main content
POST
Bulk import leads

Authorizations

Authorization
string
header
required

Use Authorization: Bearer tc_live_xxxxx

Body

application/json
list_id
string<uuid>
required
leads
object[]
required
Required array length: 1 - 2000 elements
mode
enum<string>
default:merge

For leads already in the account, merge overwrites name, email and metadata with non-empty values, appends notes with a timestamp and adds new tags. It never changes status. skip changes nothing. A phone repeated in the request keeps its last row in merge, its first in skip.

Available options:
skip,
merge
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

Bulk result

success
boolean
required
inserted
integer
required
updated
integer
required

Existing leads merged. Always 0 in skip mode.

skipped
integer
required

Rows left untouched. Equals duplicates in skip mode, 0 in merge mode.

duplicates
integer
required

Rows that matched a lead already in the account or repeated an earlier phone in the request.

total_processed
integer
required

Rows in the request.

duration_ms
integer
required