# Prospecting

> Run prospect discovery with the prospect agent and poll the append-only live event thread.

Canonical guide: <https://engine.neraperla.com/docs/prospecting>

Raw Markdown: <https://engine.neraperla.com/docs/raw/prospecting.md>

OpenAPI: <https://engine.neraperla.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.

Let the platform work out the targeting. When you maintain [Brands](https://engine.neraperla.com/docs/brands) and [Offers](https://engine.neraperla.com/docs/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.

```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.",
    "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')
```

> [!NOTE]
> `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](#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](https://engine.neraperla.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 .
```

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](https://engine.neraperla.com/docs/jobs#ownership-and-billing) 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](https://engine.neraperla.com/docs/prospecting-extensions); 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.status` is `qualified` when the search returned evidence for the match and `unknown` otherwise; the current engine doesn't return `rejected` prospects.
- `profile.company` carries what the source knows about the company: `employee_range` (its employee band, such as `1001 to 5000`; `headcount` is set only when the source gives an exact number), `revenue_range` (an annual revenue band in US dollars), and `intents`, 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.location` is where the contact is based when their record says so, otherwise the company's location.
- `qualification.reason` is why the engine matched the prospect, in its own words.
- `agent_summary` (`null` when the run reported none) is the search agent's closing note: a `title` for the results, a Markdown `message` describing what it targeted, and up to ten follow-up `suggestions`. It is generated text: its counts are the agent's own (the `prospects` array 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_email` when found and, when the contact's record has one, a `phone` (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_delivered` is `true` when 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, and `previously_delivered_job_id` names the most recent such run (`null` otherwise). 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](https://engine.neraperla.com/docs/prospecting-extensions) 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 no `work_email` and has `enrichment.status` `not_found`.
- The current engine writes no outreach drafts: every prospect has `outreach.state` `not_ready` and `outreach.draft` `null`. Write first-touch copy with [Message Templates](https://engine.neraperla.com/docs/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:

```bash
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](https://engine.neraperla.com/docs/outcomes). Bounded continuations and reusable qualification policies are [Preview extensions](https://engine.neraperla.com/docs/prospecting-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.
