# Prospect Research

> Retrieve structured company intelligence, analyze an unindexed website, and optionally add lookalikes.

Canonical guide: <https://engine.neraperla.com/docs/prospect-research>

Raw Markdown: <https://engine.neraperla.com/docs/raw/prospect-research.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

Account research is a GA synchronous lookup. It returns one typed website-intelligence record for a normalized company domain. The Prospect Research Specifications operations on this page remain separate Preview planning contracts and do not execute research.

## Retrieve an account record

Operation `public_account_research_v1_account_research_post` accepts `POST /v1/account-research`:

```bash
curl --fail-with-body --silent --show-error \
  --request POST "$BLACKPEARL_API_BASE_URL/v1/account-research" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "domain": "hubspot.com",
    "analyze": true,
    "include_similar": true
  }' | jq .
```

`domain` is required. Schemes, `www.`, paths, queries, fragments, and a trailing dot are removed before lookup. Invalid hostnames return `invalid_domain` without recording usage.

By default, an unindexed domain returns `404 account_not_found` and consumes no request unit. Set `analyze: true` to invoke the provider's on-miss website analysis, then retrieve the newly indexed record. A successful on-demand analysis consumes one additional `prospect_research` request and sets `analyzed: true`. A website that cannot be fetched returns `account_unanalyzable`; upstream analysis quota exhaustion returns `account_research_backend_quota`.

Set `include_similar: true` to add up to ten `similar_companies` with normalized identity details and a similarity score from 0 to 1. Lookalikes are best-effort enrichment: provider failure produces an empty list and does not fail the account lookup. The requested domain is removed from its own lookalikes.

## Interpret and meter the result

The response groups fields by purpose:

| Area | Contents |
|---|---|
| `identity` | Name, domain, URL, summary, history, industry, structure, founders, values, and descriptive language. |
| `scale` | Employee and office counts, stated users, revenue, TAM, and primary location. |
| `market` | B2B/B2C posture, target customers, products, services, customers, competitors, and testimonial presence. |
| `digital` | Important site URLs, social links, integrations, detected technology, languages, support, API, trial, app, content, commerce, and subscription signals. |
| `signals` | AI, compliance, awards, CSR, inclusion, environmental, geographic, IP, IPO, disruption, and hiring signals. |
| `contacts` | Up to ten provider-surfaced names, titles, business emails, and professional profile URLs. Fields may be null. |
| `similar_companies` | Optional lookalikes requested with `include_similar`. |

Also retain `domain`, `retrieved_at`, `schema_version`, `analyzed`, and `provenance`. Successful responses come from the configured research backend; an unconfigured integration fails closed instead of returning synthetic company evidence.

Every successful lookup consumes one `prospect_research` request. An on-miss analysis consumes one additional request before the successful lookup. Validation, entitlement, quota, and not-found failures do not consume a successful lookup unit. Similar-company enrichment does not add a unit.

Provider-derived facts can be incomplete, stale, or incorrect. Preserve provenance and retrieval time, render values as untrusted data, and review material claims before using them in generated collateral or decisions about people.

## Errors and retry behavior

`capability_disabled`, `invalid_domain`, `account_not_found`, and `account_unanalyzable` require a caller or source change. `quota_exceeded` and `account_research_backend_quota` require a reset or capacity change. `account_research_not_configured` and `account_research_unauthorized` require an operator configuration fix. Retry `account_research_unavailable` or `account_research_backend_error` only with bounded backoff. See [Errors and retry decisions](https://engine.neraperla.com/docs/errors).

## Preview research-planning contracts

**Specification preview** — this surface accepts and stores typed plans; execution is not yet available. Storing a research specification never runs research; only the synchronous account lookup above performs work.

Prospect Research Specifications are Preview, contract-only plans. They bind reviewed Audience members to closed business-research lenses, evidence policy, and hard collection budgets. Creating one performs no web search, provider request, model call, enrichment, scoring, or generation.

Preview operation `create_prospect_research_specification_v1_prospect_research_specifications_post` creates an immutable plan. Preview operation `list_prospect_research_specifications_v1_prospect_research_specifications_get` lists plans with cursor pagination. Preview operation `get_prospect_research_specification_v1_prospect_research_specifications__specification_id__get` reads one plan.

Do not interpret a specification as researched evidence or use it to make claims about a person. Any future person-level executor must retain source attribution, freshness, confidence, lawful purpose, and review controls.
