Prospect Research

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

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:

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.

Preview research-planning contracts#

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.