Find and export leads

Preview your targeting, understand costs, then run the intended search.

Export leads already on a campaign

With campaignLeads:read, call Export campaign leads. Each response is a CSV page. If X-Next-Cursor is returned, request the next page with that cursor and identical filters. Only the first page includes column headings. A single response may not contain every lead.

Import leads you already have

Use Add campaign leads with a workspace key that has campaigns:write. Send JSON lead objects in batches of up to 1,000 and within the 1 MiB serialized request limit. Per-lead customVariables preserve personalized values for sequence placeholders.

The API does not receive a CSV file. Map CSV columns in your client, use a stable idempotency key for each batch, poll the returned operation, and read back a small sample with campaignLeads:read. Import your own CSV leads includes the mapping, a no-network Python planner, and retry guidance.

Adding leads to an active campaign can enroll them in its live sequence. A draft remains a draft after import.

Free lead capacity

Every lead stored in a campaign counts against the workspace's lead capacity. To free capacity, delete leads you no longer need with Delete campaign leads: send { "all": true }, or { "leadIds": [...] } with up to 100 campaign lead ids. Deleting a whole campaign with Delete campaign also frees its leads' capacity.

Both need campaigns:write and an Idempotency-Key, and both return an operation. The capacity is free once the operation succeeds, because it waits for the outreach provider to confirm the delete.

Deletes are permanent. Export the leads first if you might need them again.

Find new leads for a campaign

Use a workspace API key with campaigns:write.

Prepare filters, or use AI filter suggestions to turn a brief into a proposed filter document.
Check workspace usage first: credits left and contact capacity (used, limit, remaining). Then preview the search. Review the filters and matching count; preview does not attach leads or spend credits.
When ready to spend credits, submit those same filters and a leadCount to Search campaign leads. Use an Idempotency-Key to prevent an accidental repeat search on retry.
Track the operation, then check the campaign's leads as they arrive.

Executing a search is the paid step. On an active campaign, new leads enter its live email sequence. Use a draft when preparing a campaign you do not want sending yet.

Company size accepts the fixed headcount bands (for example 51-100) and custom ranges written custom:min-max (for example custom:3-15), alone or together. Both ends are whole numbers with 1 <= min < max <= 1000000; anything else is rejected with a 422 before any credits are spent.

Limit contacts per company

Add maxLeadsPerCompany (1 to 100) to the filters to stop one company from filling the list. The provider has no per-company limit, so the cap is applied as leads come back: they are kept in the provider's order, and extra contacts from a company that already has that many are dropped. Three things to know:

A paid search can attach fewer leads than leadCount.
A preview caps its sample only. The match count is before the cap, and the preview warns you.
oneLeadPerCompany: true is the same as maxLeadsPerCompany: 1. Sending it with any other cap returns 422. The cap applies to the B2B database and counts contacts within the one search, not leads already in the campaign.

A successful campaign-search operation means the search was dispatched, not that every lead has arrived. Searching and attaching can take several minutes.

Find leads to use outside a campaign

Use standalone preview with leads:read, then standalone search with leads:search. These require a workspace API key. Send an Idempotency-Key for the paid request. The paid search's completed result includes downloadUrl and expiresAt; download the CSV before the link expires.