Address Research

Address Research is a bounded, source-linked research resource for one authorized location context. It can accept one canonical address, locality, GeoJSON context, or frozen Territory Analysis. It is not a people lookup, ownership determination, contact-enrichment service, outreach authorization, or a substitute for a Territory Analysis target read.

Operations and scopes

Use an Application key with current Account, Application, and Workspace access. address_researches:create is required for Create; address_researches:read is required for all reads.

Method	Path	MCP tool	Meaning
POST	/v1/workspaces/{workspace_ref}/address-researches	address_researches.create	Accept one bounded research run.
GET	/v1/workspaces/{workspace_ref}/address-researches	address_researches.list	List authorized research runs.
GET	/v1/workspaces/{workspace_ref}/address-researches/{address_research_ref}	address_researches.get	Read lifecycle, billing, coverage, and completion state.
GET	/v1/workspaces/{workspace_ref}/address-researches/{address_research_ref}/results	address_researches.results.list	Read policy-permitted direct source statements.
GET	/v1/workspaces/{workspace_ref}/address-researches/{address_research_ref}/sources	address_researches.sources.list	Read source-admission decisions and aggregate reliability.

Create requires a permanent Idempotency-Key and exactly one input selector. An optional maximum research-credit ceiling is frozen with the accepted request; otherwise the configured Workspace or Account default applies. Reuse the same permanent key to retrieve the same accepted request. Do not use a fresh Create request to represent a retry of an existing run.

An accepted response is not a completed research result. Read the run and its paginated result/source collections to distinguish accepted, complete, partial, and needs_attention states. The OpenAPI document is the canonical transport schema.

Direct statements and privacy

Results contain only source-linked, policy-permitted direct statements with provenance, authority tier, claim status, observed time, and an evidence digest. A result must not make a client infer a person's identity, ownership, residence, household, employment, relationship, or contact information. Raw provider requests, responses, documents, private query plans, and disallowed source URLs are never public result fields.

An optional source URL is returned only when the source-sharing policy permits it. An omitted URL, an empty result collection, or a partial run does not imply that the source was inaccessible, that no person exists, or that a claim is false.

Source reliability

The Sources endpoint reports an aggregate source profile alongside the decision and coverage for the current run. The profile is useful for interpreting evidence quality, but it does not prove that the current run completed and it is not a source of private evidence.

Field	Meaning
attempts	Evaluated candidates in the aggregate profile; it is not a count of completed captures.
admissionRate	Admitted candidates divided by attempts (evaluated candidates).
addressMatchRate	Exact frozen-address matches divided by completed parser outcomes with a reported match outcome.
parseRate	Successful parses divided by validated parser-terminal outcomes.
directClaimYield	Count of direct, policy-permitted claims emitted in the aggregate profile.
averageLatencyMs	Mean observed elapsed time across completed parser outcomes with authoritative timing.
totalCredits	Authoritative incurred capture credits across included outcomes; not a quote, reservation, or predicted price.
lastSuccessAt	Most recent successful completed parser outcome timestamp; not a rate-limit lease or last-attempt timestamp.

attempts and admissionRate are candidate-assessment metrics; completed parser outcomes govern only addressMatchRate, parseRate, averageLatencyMs, and lastSuccessAt. A null field means there is no eligible data for that metric; it does not mean zero. For directClaimYield, zero is a known zero and is different from missing completion data.

Errors and safe handling

Malformed pagination is reported as invalid_pagination with HTTP 400. Invalid input and an unconfigured research limit are correctable request errors. Missing or out-of-scope runs are not found or denied without revealing another Workspace's data. Invalid or revoked keys fail authentication. Upstream or fanout uncertainty should be retried only with the same permanent idempotency key when the response directs that behavior.

Use the normal REST/MCP read operations to observe a durable run. Do not call provider, queue, repair, or internal administration routes to diagnose a public response.