Audiences and types

An audience is a set of leads that match your filters. You build it, preview it for free, and Reveal the leads you want.

TypesCopy Anchor Link

Find topic ids with GET /v1/topics?q=solar&type=b2c, or let POST /v1/describe pick them. intent and active_within_days only apply to intent audiences. See the filters reference.

LifecycleCopy Anchor Link

1. building. POST /v1/audiences returns at once with this status. Building is free.
2. ready. The preview is available. match_count is how many leads match the filters in full, and total_count how many of them the audience holds for preview and Reveal: up to 500 from a build. When total_is_capped is true more leads match than the audience holds; show match_count, or total_count as "N+" when match_count is null.
3. failed. The build didn't finish. Nothing was charged; try again or change the filters.

Poll GET /v1/audiences/{id}, or subscribe to the audience.ready webhook, which fires for both ready and failed.

A build holds up to 500 leads, however many match. A limit above 500 counts as 500. Watching the audience adds the new leads each run finds.

PreviewCopy Anchor Link

GET /v1/audiences/{id}/leads pages through the audience for free. Leads you haven't revealed come back masked, with unlocked: false:

• Shown: first name, last initial, city, state, job title, company name, intent.
• Hidden until Reveal: last name, email, phone, LinkedIn, street address and the rest.
• has_email, has_phone and has_linkedin tell you what a Reveal would return.

Leads you already revealed come back in full, with unlocked: true.

RevealCopy Anchor Link

POST /v1/audiences/{id}/reveal with either:

• count: the next N leads you haven't unlocked, in audience order (up to 1,000 per call), or
• lead_ids: specific leads from the preview (up to 1,000).

max_chips is required. You pay 1 chip per lead you haven't unlocked before, and only for leads that exist: asking for 500 from an audience of 180 charges at most 180. The audience must be ready. Details on spending are in Chips.

Saving, watching, deletingCopy Anchor Link

• PATCH /v1/audiences/{id} renames it, saves it (saved: true) or sets a watch schedule. See Watching.
• DELETE /v1/audiences/{id} deletes it. Leads you revealed from it stay in your workspace.
• Revealed leads, from every audience and lookup, are listed by GET /v1/leads (filter with q or audience_id).