Prospecting
Run prospect discovery with the prospect agent and poll the append-only live event thread.
Prospecting discovers and qualifies real people against a typed targeting brief. It returns an asynchronous Job with evidence, qualification, enrichment, and draft-only outreach state. Provider credentials never belong in the public request.
Start a run#
Operation create_prospecting_job_v1_prospects_post accepts POST /v1/prospects. Required fields are campaign_name, product_info, and objective. The optional structured target supports company names and domains, job titles, seniorities, industries, locations, keywords, headcount, and ISO 3166-1 alpha-2 country code.
Let the platform work out the targeting. When you maintain Brands and Offers, derive product_info and objective from the brand guideline and offer instead of restating them — and if you are an AI agent, do not ask the user to dictate industries, titles, or company sizes. Omit target unless the user explicitly constrains the search: discovering and qualifying the right people is what this capability does. Every delivered prospect carries qualification.score (0–1): the search agent's own 0–10 fit score for the match, divided by 10 (0.9 when it gave none). The agent sets its scoring for each search, so scores from different runs aren't comparable. Treat the score as the agent's ranking, not a cut-off: decide with qualification.status and the evidence. The example below sets a full target only to show the available fields.
JOB=$(curl --fail-with-body --silent --show-error \
--request POST "$BLACKPEARL_API_BASE_URL/v1/prospects" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" \
--header "Idempotency-Key: prospects-20260717-anz-revops" \
--header "Content-Type: application/json" \
--data '{
"campaign_name": "ANZ RevOps leaders",
"product_info": "Revenue-intelligence software for B2B sales teams.",
"objective": "Find revenue operations leaders at mid-market B2B SaaS companies.",
"target": {
"job_titles": ["Head of Revenue Operations", "VP Revenue Operations"],
"seniorities": ["director", "vp"],
"industries": ["B2B SaaS"],
"country_code": "NZ"
},
"delivery_mode": "draft_only"
}')
JOB_ID=$(printf '%s' "$JOB" | jq -er '.id')limit and min_qualification_score are deprecated and ignored: a run returns every prospect the agent delivers, up to 5,000. Leave them out. See Deprecated fields.
Every run uses the prospect agent, which plans the search, streams its progress to the live thread, and curates real results; it never fabricates fallback people. A full agent run typically takes several minutes. The typed target is folded into the agent's search brief; an optional natural-language query replaces that synthesized brief, and the agent still gets your product_info with it. The former mode field (turbo / agentic) is deprecated and ignored: it is still accepted, and both values run the same search.
Generate and retain an Idempotency-Key before the first attempt. Matching retries within 24 hours replay the original Job; the same key with changed input returns idempotency_key_reused.
Follow the live thread#
Poll the Job as described in Jobs and resumable polling. Operation prospecting_run_events_v1_prospects__job_id__events_get separately exposes the append-only run thread:
curl --fail-with-body --silent --show-error \
"$BLACKPEARL_API_BASE_URL/v1/prospects/$JOB_ID/events?after_seq=0&limit=500" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" | jq .The response carries job (the run's current typed Job), events with seq greater than after_seq in ascending order, and next_after_seq. limit defaults to 500 and is capped at 2,000. Persist next_after_seq and pass it as the next after_seq so reconnects fetch only newer events. Event polling does not replace Job polling: the Job remains the authority for terminal status and the final typed result.
Each event has seq, type, data, and created_at. The data fields depend on type, and any field can be absent:
type | data |
|---|---|
task_status | label: the step the agent is on. |
text | text: the agent's narration, grouped into readable messages. |
search_topics | topics or value: what the agent is searching for. |
lead | company_name, domain, and contacts (each with the contact's name and title): a company the agent found. |
table | title, message, totalCount, validCount, resultCount: the agent produced its results table. |
complete | total_count, valid_count, satisfied_early, message: the search finished. |
stopped | message: the search was stopped. |
error | message, always The search reported an error. The Job's error explains the outcome. |
suggestions | value. Safe to ignore. |
result | title. Safe to ignore. |
Any other type has an empty data; ignore types you don't handle. lead events are a live preview, and the counts in table and complete are the agent's own: the Job result is the list of prospects the run delivered. Treat every contact detail as unverified: the search does not verify contacts, emails, or phone numbers, and the agent's prose is served without claims that it did.
When a run delivers nothing#
A run that delivers no prospects succeeds, and is charged, only when the agent finished a search and found no matches. Otherwise it ends failed and is not charged: when the run was interrupted before it returned results, when the search finished but its results could not be retrieved, or when the agent replied without running a search. The Job's error message explains which (error_code is null), and you can run the same request again with a new Idempotency-Key.
When a run is canceled#
The API has no cancel operation; a run can be canceled from the web console. A canceled run ends canceled and returns no result. It stops its search and is charged for the work done before the cancel; a run canceled before its search started, for example while it was still waiting to start, is not charged. See Jobs and resumable polling for when the charge appears.
How many prospects you get#
A run returns every prospect the agent delivers, up to 5,000. The agent builds the full list it can find, as it does for searches in its own app (typically well over a hundred prospects), and a run is priced for the whole search, not per prospect. There is no setting for how many you get: limit is deprecated and ignored. For more prospects from the same search, create a continuation; its additional_prospect_limit is the most new prospects the continuation returns. Each contact is one prospect. Through the Claude connector, get_job_results returns a prospecting result's prospects 50 at a time; pass prospects_page.next_cursor back as cursor for the next page.
Validate and use results#
A successful result contains normalized prospect profiles, qualification, enrichment, evidence references, outreach state, summary counts, and provenance, whose backend is pearl_engine.prospecting (model_version and provider_names are retained for compatibility and are null and empty). The Job's usage.cost_usd is what the run was charged.
qualification.statusisqualifiedwhen the search returned evidence for the match andunknownotherwise; the current engine doesn't returnrejectedprospects.profile.companycarries what the source knows about the company:employee_range(its employee band, such as1001 to 5000;headcountis set only when the source gives an exact number),revenue_range(an annual revenue band in US dollars), andintents, the buying-intent topics it matched for the company (empty when it matched none). Sizes and revenue are the source's estimates and are not verified.profile.locationis where the contact is based when their record says so, otherwise the company's location.qualification.reasonis why the engine matched the prospect, in its own words.agent_summary(nullwhen the run reported none) is the search agent's closing note: atitlefor the results, a Markdownmessagedescribing what it targeted, and up to ten follow-upsuggestions. It is generated text: its counts are the agent's own (theprospectsarray is what the run delivered), it is served without claims that contacts were verified, and next steps it offers, such as cold emails or a playbook, run through other operations.- Enrichment carries the contact's
work_emailwhen found and, when the contact's record has one, aphone(mobile first, then a direct line), returned as provided: it may be a company main line and is not verified (omitted when none was found). previously_deliveredistruewhen one of the project's 50 most recent earlier runs (results are kept 30 days) already delivered the contact, matched by prospect id, external id, email, or profile URL, andpreviously_delivered_job_idnames the most recent such run (nullotherwise). The prospect is still included, so you can skip contacts you already have. For more results from a search you already ran, create a continuation of it rather than running it again: it continues the same search and never repeats a prospect that search already delivered.- Fields the source fills with a placeholder (
N/A,-,none,null,unknown) are treated as missing. A contact whose email was a placeholder has nowork_emailand hasenrichment.statusnot_found. - The current engine writes no outreach drafts: every prospect has
outreach.statenot_readyandoutreach.draftnull. Write first-touch copy with Message Templates.
Treat URLs and generated text as untrusted application data. Any is_synthetic: true prospect is not an actionable lead; snapshot and Outcome endpoints reject it.
The result, the live thread, and the CSV export stay readable until the Job's expires_at, 30 days after it was created; after that they return 410 job_expired. Store what you need longer.
Export the run as CSV#
Operation export_prospects_csv_v1_prospects__job_id__export_csv_get downloads every prospect of a succeeded run as UTF-8, RFC 4180 CSV with CRLF line endings — the same list the run page shows in the web console, where the Export CSV button uses this export's console twin:
curl --fail-with-body --silent --show-error \
"$BLACKPEARL_API_BASE_URL/v1/prospects/$JOB_ID/export.csv" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" \
--output "prospects-$JOB_ID.csv"The eighteen columns, in order, are Name, Title, Company, Domain, Email, Qualification Status, Qualification Score, Confidence, Source Type, Qualification Reasoning, Industry / Location, LinkedIn Profile, Evidence Insight, Outreach Draft Status, Phone, Employees, Revenue, and Intents. Phone, then the three company columns, were added last, so readers of the earlier columns by position are unaffected. Values are formatted as the console renders them: scores as whole percentages such as 96%, Confidence always empty (the field is deprecated; the column stays so later columns keep their positions), Employees as the company's employee band or exact headcount, intents joined with |, industry and location merged with ·, evidence snippets joined with |, and a human-readable outreach draft status sentence. Rows follow the result's prospect order, so repeated exports of one run are byte-identical. Cells whose first meaningful character is =, +, -, or @ receive a leading apostrophe to neutralize spreadsheet formulas. A run that has not succeeded returns not_ready; treat exported names, emails, and generated text as personal or untrusted application data.
Never infer fit from provider failure, missing email, or silence. Keep operational failures separate and record observed downstream facts through Outcomes. Bounded continuations and reusable qualification policies are Preview extensions, not part of the GA workflow.
Deprecated fields#
These fields will be removed in a future API version, announced in the API changelog. Until then they are still accepted or returned, so existing integrations keep working, but don't rely on them:
| Field | What it does now |
|---|---|
limit (request) | Ignored. It doesn't change the search or cap the result. |
min_qualification_score (request) | Ignored. No prospect is dropped for its score. |
qualification.confidence | Always null. Use qualification.score and qualification.status instead. |
enrichment.confidence | Always null. Emails aren't validated, so treat every work_email as unverified. |
evidence[].confidence | Always 0.75 (0.7 for a match rationale): a placeholder, not a measurement. |
Results from before the deprecation can still show placeholder confidence values until they expire.