Skip to main content
POST
Create lead list API

Frequently asked questions

The request returns immediately with a list_id and status: "processing". A background job assembles the rows. Poll the list detail endpoint until status is ready, then preview or export it.
After the job completes, on the actual number of rows delivered — 1 credit each. Nothing is charged upfront, and a failed job charges nothing at all. At create time we only check that your balance covers list_size, the maximum the job could deliver. If your balance is lower than list_size, the list is capped to your balance rather than rejected.
or matches domains running any of the listed technologies. and requires all of them. and_not requires the first and excludes the rest — the way to build “running Shopify but not Klaviyo”.
Set has_email: true or has_phone: true to restrict the list to domains where the crawler found contact details. Either way, every export carries the contact columns — emails, phones and five social profile URLs — so you do not have to filter on them to receive them.
Yes. Pass segment_id instead of technology filters and the list is built from that audience’s membership, with all the company and contact columns attached.
Concurrency is capped per plan: 1 on Free, 3 on Pro, 5 on Scale and 10 on Enterprise. Lists are between 1,000 and 100,000 rows and their results are deleted 60 days after creation.

Authorizations

Authorization
string
header
required

API key in format tapi_live_[32-char] (live) or tapi_test_[32-char] (test)

Body

application/json

The filter set that defines a lead list. Technology filters and company filters combine with AND.

name
string
required
Example:

"US SaaS Companies using Cloudflare"

list_size
integer
required

Maximum rows to deliver, and therefore the maximum charge.

Required range: 1000 <= x <= 100000
Example:

10000

technologies
object
keywords
object
website_type
string
Example:

"company_only"

countries
string[]
Example:
industries
string[]
Example:
employees
string[]
Example:
has_email
boolean

Only domains where the crawler found an email address.

has_phone
boolean

Only domains where the crawler found a phone number.

languages
string[]
Example:
web_countries
string[]

ISO-2 codes or English names. Unresolvable values are rejected at create time.

Example:
segment_id
string

Export a saved audience as a lead list instead of specifying technology filters.

Example:

"seg_8f3a2c1b"

selected_columns
string[]
Example:

Response

The list was accepted and is being built

success
boolean
Example:

true

data
object