Skip to main content
POST
Import leads into a smart list

Authorizations

X-API-Key
string
header
required

Company API key - scoped to a specific company. Generate from the Integrations page in your dashboard.

Body

application/json

Lead import criteria plus the destination smart list

companyId
string
required

Company ID (bills its data credits)

listId
string
required

Destination smart list id. Must already exist.

audience
object

Buyer-intent keyword search — the highest-signal input. { segmentSearches: string[] } is free-text topics the lead is actively shopping for (e.g. ['CRM software']); optional b2b: bool biases to business vs consumer intent. Distinct from filters.businessProfile.companyDescription, which describes what the company IS. Combine with filters to intersect intent and firmographics.

audienceName
string

Name for the generated audience. Default "Leads".

count
integer

Max contacts to import. Required when importAll is false. Note the full audience is still built vendor-side.

daysBack
integer

Recency window for intent data, 2-10, default 7.

filters
object

Attribute filters (each a string[] unless noted). Location: city, state, zip_codes. Person: age {minAge,maxAge}, gender, ethnicity, language, education, occupationGroup. Financial: incomeRange, netWorth, homeowner, married, creditRating, creditCardUser, investor. Housing: dwellingType, estimatedHomeValue, mortgageAmount {min,max}. Contact quality: contactNotNulls (fields that must be present). businessProfile (nested object): industry, seniority, department, jobTitle, companyName, companyDomain, companyDescription, employeeCountRange, annualRevenue, sicCodes, naicsCodes. Use lead_field_options for the enumerated fields' valid values.

importAll
boolean

true = import every matching contact. Defaults to true only when no count is given; pass count to import a slice.

saveAudience
boolean

Attach this configuration to the list so it can be edited and auto-refreshed later. Ignored when the list already has an audience — an existing one is never overwritten.

segment
string[]

Premade segment externalIds from lead_segments (e.g. "b2b_12636", "b2c_1253").

Response

The import was queued; poll taskId for progress

The queued background import

listId
string

The destination smart list.

message
string

Human-readable status message

status
string

Always "background" — the import runs asynchronously.

taskId
string

Background task id for the running import.