Audiences
Run evidence-backed audience discovery, then materialize immutable review snapshots from real prospects.
Audiences has two complementary workflows. The live audience workflow — powered by the engine ranked first on GTM-Bench — runs asynchronous discovery and returns scored candidates. The snapshot workflow freezes selected prospects from a successful Prospecting job so people can review and export a stable list. Neither workflow authorizes or sends outreach.
Run one audience discovery#
Operation create_audience_v1_audiences_post accepts an AudienceInput at POST /v1/audiences. The required objective describes the companies and buyers to find. target_size is 1 through 2,000, max_contacts_per_company is 1 through 10, and optional seller, product, ICP, exclusion, and intent context refines the run.
JOB=$(curl --fail-with-body --silent --show-error \
--request POST "$BLACKPEARL_API_BASE_URL/v1/audiences" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" \
--header "Idempotency-Key: audience-run-20260717-anz-revops" \
--header "Content-Type: application/json" \
--data '{
"objective": "Find revenue operations leaders at B2B SaaS companies in Australia and New Zealand.",
"target_size": 100,
"max_contacts_per_company": 3,
"model": "default"
}')
JOB_ID=$(printf '%s' "$JOB" | jq -er '.id')The response is an asynchronous Audience job. The request also saves its targeting as a Campaign, returned as the job's campaign_id, so you can run later cycles with POST /v1/campaigns/{campaign_id}/cycles. Poll the job using Jobs and resumable polling. Its stages are, in order, icp, intent, and industries (the campaign's setup, reused by later cycles), then retrieval, prelim, deep, final, and playbooks. Each stage is pending, running, completed, skipped, or failed. The job's usage.cost_usd is what the cycle was charged. After the Job succeeds, operation list_audience_candidates_v1_audiences__job_id__candidates_get pages GET /v1/audiences/{job_id}/candidates. Pass each opaque next_cursor back unchanged and stop when it is null. Optional q filtering is applied before pagination.
curl --fail-with-body --silent --show-error \
"$BLACKPEARL_API_BASE_URL/v1/audiences/$JOB_ID/candidates?limit=50" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" | jq .Candidate rows are discriminated by result_shape: a company row has company scoring plus contacts, while a contact row is one scored contact with company context. Results remain available until the job's expires_at; save anything needed beyond the 30-day retention window.
Operation export_audience_candidates_csv_v1_audiences__job_id__candidates_csv_get downloads the full candidate list of a succeeded job as UTF-8, RFC 4180 CSV with CRLF line endings at GET /v1/audiences/{job_id}/candidates.csv — one row per contact with the company columns repeated, and a single row for a company without contacts. Cells whose first meaningful character is =, +, -, or @ are neutralized with a leading apostrophe. A job that has not succeeded returns not_ready.
Materialize an immutable snapshot#
Use a snapshot when a successful, non-synthetic Prospecting result should become a durable review set. Operation create_audience_v1_audience_snapshots_post accepts a caller-owned key, a display name, the source prospecting_job_id, and an optional subset of prospect_ids.
SNAPSHOT=$(curl --fail-with-body --silent --show-error \
--request POST "$BLACKPEARL_API_BASE_URL/v1/audience-snapshots" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" \
--header "Content-Type: application/json" \
--data "{
\"key\": \"anz-revops-2026q3\",
\"name\": \"ANZ RevOps leaders\",
\"prospecting_job_id\": \"$PROSPECTING_JOB_ID\"
}")
AUDIENCE_ID=$(printf '%s' "$SNAPSHOT" | jq -er '.id')The create namespace is project, API-key environment, and key. An exact replay returns the original resource with HTTP 200; different normalized input under the same key returns audience_idempotency_conflict. The server stores a hash of the normalized source result and copies only validated prospect fields. A later provider or Job change cannot rewrite the snapshot.
Operation list_audiences_v1_audience_snapshots_get lists snapshots newest first with cursor pagination. Operation get_audience_v1_audience_snapshots__audience_id__get reads one snapshot. Resources in another project or live/test environment resolve as not found.
Review members#
Operation list_audience_members_v1_audience_snapshots__audience_id__members_get pages the frozen members. Filters include text query, review, qualification, enrichment and outreach states, minimum score (min_score), evidence or work-email presence, and exact prospect ID. Cursors are bound to the filter set; restart pagination when a filter changes.
min_score compares each member's qualification.score, the search agent's own fit score for its run, so a min_score filter can drop qualified members. Filter on qualification_status instead of the score unless you have checked the scores in your snapshot.
Operation review_audience_members_v1_audience_snapshots__audience_id__reviews_post records an append-only included or excluded decision for 1 through 100 member IDs. Generate one review_key per logical decision and retain it for retries.
curl --fail-with-body --silent --show-error \
--request POST "$BLACKPEARL_API_BASE_URL/v1/audience-snapshots/$AUDIENCE_ID/reviews" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" \
--header "Content-Type: application/json" \
--data "{
\"review_key\": \"review-20260717-batch-1\",
\"member_ids\": [\"$AUDIENCE_MEMBER_ID\"],
\"decision\": \"included\",
\"reason_code\": \"verified-fit\"
}"Review means curation, not consent or delivery permission. Every snapshot and member returns outbound_authorized: false, including included members.
Export and safety#
Operation export_audience_csv_v1_audience_snapshots__audience_id__export_csv_get exports the current filtered snapshot as CSV. Members keep the prospect's enrichment.phone when the run found one, but the snapshot CSV has no phone column; use the prospecting run export when you need phone numbers. Every list surface has a CSV export: this snapshot export, the live audience candidate export above, and the prospecting run export. Treat names, emails, profile details, generated drafts, and evidence as personal or untrusted application data. Apply your own lawful-basis, suppression, consent, access-control, retention, and dispatch-time checks outside Blackpearl.
Common failures are not_ready, job_expired, audiences_result_unavailable, prospecting_job_not_found, synthetic_prospecting_result, audience_idempotency_conflict, invalid_cursor, entitlement, quota, and budget errors. Follow Errors and safe retries.