# Prospecting

> Run turbo or agentic prospect discovery and poll the append-only live event thread.

Canonical guide: <https://api.blackpearl.com/docs/prospecting>

Raw Markdown: <https://api.blackpearl.com/docs/raw/prospecting.md>

OpenAPI: <https://api.blackpearl.com/v1/openapi.json>

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.

```bash
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](https://api.blackpearl.com/docs/jobs). Operation `prospecting_run_events_v1_prospects__job_id__events_get` separately exposes the append-only run thread:

```bash
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](https://api.blackpearl.com/docs/outcomes). Bounded continuations and reusable qualification policies are [Preview extensions](https://api.blackpearl.com/docs/prospecting-extensions), not part of the GA workflow.