Prospecting

Run turbo or agentic prospect discovery 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.

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.",
    "mode": "turbo",
    "target": {
      "job_titles": ["Head of Revenue Operations", "VP Revenue Operations"],
      "seniorities": ["director", "vp"],
      "industries": ["B2B SaaS"],
      "country_code": "NZ"
    },
    "limit": 25,
    "min_qualification_score": 0.9,
    "delivery_mode": "draft_only"
  }')

JOB_ID=$(printf '%s' "$JOB" | jq -er '.id')

mode: turbo uses the fastest database-search workflow. mode: agentic asks the connected prospect agent to plan and curate the search; it fails clearly when the private backend does not support that mode and never fabricates fallback people. An optional natural-language query overrides the synthesized search brief.

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 .

Persist next_after_seq and pass it as the next after_seq so reconnects fetch only newer agent status, streamed message, and discovered-lead events. Event polling does not replace Job polling: the Job remains the authority for terminal status and the final typed result.

Validate and use results#

A successful result contains normalized prospect profiles, qualification, enrichment, evidence references, draft-only outreach, summary counts, usage, and backend provenance. 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.

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.