Schemas

Generated from openapi.json. Field paths use dots for nested objects and [] for array items.

ApiKey

An API key’s metadata.

Field	Type	Required	Description
id	string	yes	The key id.
project_id	string	yes	Project the key belongs to.
name	string	yes	Name.
environment	enum: “live”, “test”	yes	live or test.
prefix	string	yes	The key’s first characters, to recognize it.
scopes	array of enum: “decisions:write”, “index:read”, “outcomes:write”, “watches:manage”, “vendors:call”, “account:read”, “account:manage”, “keys:manage”	yes	Scopes granted.
status	enum: “active”, “rotating”, “revoked”, “expired”	yes	Lifecycle status.
rate_limit_per_minute	integer	yes	Requests per minute allowed.
daily_spend_cap_usd	number or null	yes	Daily spend cap, or null for none. US dollars, up to 6 decimals.
ip_allowlist	array of string	yes	CIDR blocks the key may be used from; empty means anywhere.
expires_at	string or null (date-time)	yes	Expiry, or null for none.
last_used_at	string or null (date-time)	yes	Last successful use, or null.
created_at	string (date-time)	yes	When the key was created.

AuditEntry

One append-only audit log entry.

Field	Type	Required	Description
id	string	yes	The audit entry id.
action	enum (21 values)	yes	What happened.
actor	object	yes	Who did it.
actor.kind	enum: “user”, “key”, “system”	yes	Kind of actor.
actor.id	string or string or null	yes	The usr_ or key_ id, or null for system.
actor.role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”, null	yes	The user’s role at the time, for user actors.
target	object or null	yes	What it was done to, if a single resource.
target.type	string	yes	Kind of resource, for example key or icp.
target.id	string	yes	The resource id.
ip	string or null	yes	Client IP address, if the action came over the network.
metadata	object	yes	Action details (for example old and new scopes). Never secrets.
created_at	string (date-time)	yes	When it happened.

BalanceResponse

Current balances.

Field	Type	Required	Description
balance_usd	number	yes	Cash balance (live keys). US dollars, up to 6 decimals.
test_balance_usd	number	yes	Non-cash test balance (test keys). US dollars, up to 6 decimals.
auto_topup	object	yes	Auto top-up settings (optional, phase 2).
auto_topup.enabled	boolean	yes	Whether auto top-up is on.
auto_topup.threshold_usd	number or null	yes	Balance that triggers a top-up. US dollars, up to 6 decimals.
auto_topup.pack_usd	enum: 20 or enum: 50 or enum: 200 or null	yes	Pack bought on trigger.
as_of	string (date-time)	yes	When the balance was read.

Calibration

How p was calibrated (spec 6.4).

Field	Type	Required	Description
basis	enum: “org”, “segment”, “global”	yes	org (your own outcomes), segment (your ICP’s segment) or global: how much to trust p.
n_outcomes	integer	yes	Outcomes behind the calibration map used.
threshold	number	yes	The threshold answer applied to p.

CandidateContact

One candidate contact. LinkedIn-sourced data is not accepted.

Field	Type	Required	Description
name	string	no	Full name.
title	string	yes	Job title.
seniority	enum: “owner”, “c_level”, “vp”, “director”, “manager”, “senior”, “entry”, “unknown”	no	Seniority, if known.
department	string	no	Department or function.
email	string (email)	no	Work email, if known.
firm	FirmReference	no	A firm reference: exactly one of firm_id, domain, name (with an optional hint), lei, cik, crd or companies_house.
firm.firm_id	string	no	A firm id from Verdict’s index.
firm.domain	string	no	The firm’s web domain.
firm.name	string	no	The firm’s legal or trading name.
firm.hint	object	no	Optional country, city or domain to disambiguate the name.
firm.hint.country	string	no	ISO 3166-1 alpha-2 country of the firm’s headquarters.
firm.hint.city	string	no	City of the firm’s headquarters.
firm.hint.domain	string	no	A domain the firm is known to use.
firm.lei	string	no	The firm’s Legal Entity Identifier.
firm.cik	string	no	The firm’s SEC Central Index Key.
firm.crd	string	no	The firm’s CRD number.
firm.companies_house	string	no	The firm’s UK Companies House number.
title_observed_at	string (date-time)	no	When you last saw this title, to judge staleness.

ConsoleOrg

An organization the user is a member of.

Field	Type	Required	Description
id	string	yes	Organization id.
name	string	yes	Organization name.
slug	string	yes	URL-safe organization slug.
role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	The user’s role in this organization.
created_at	string (date-time)	yes	When the organization was created.

ConsoleOrgsResponse

The organizations the user belongs to.

Field	Type	Required	Description
data	array of ConsoleOrg	yes	Organizations, oldest membership first.
data[].id	string	yes	Organization id.
data[].name	string	yes	Organization name.
data[].slug	string	yes	URL-safe organization slug.
data[].role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	The user’s role in this organization.
data[].created_at	string (date-time)	yes	When the organization was created.

ConsoleSession

The current console session.

Field	Type	Required	Description
user	ConsoleUser	yes	A console user.
user.id	string	yes	User id.
user.email	string (email)	yes	The user’s verified email.
user.totp_enabled	boolean	yes	Whether TOTP is turned on.
orgs	array of ConsoleOrg	yes	Organizations the user belongs to.
orgs[].id	string	yes	Organization id.
orgs[].name	string	yes	Organization name.
orgs[].slug	string	yes	URL-safe organization slug.
orgs[].role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	The user’s role in this organization.
orgs[].created_at	string (date-time)	yes	When the organization was created.
mfa_verified	boolean	yes	Whether this session has passed TOTP. When the user has TOTP on and this is false, org actions answer 401 until POST /v1/console/totp/verify succeeds.
idle_expires_at	string (date-time)	yes	When the session expires if it is not used again (7 days after last use).

ConsoleUser

A console user.

Field	Type	Required	Description
id	string	yes	User id.
email	string (email)	yes	The user’s verified email.
totp_enabled	boolean	yes	Whether TOTP is turned on.

ConsumeMagicLinkRequest

Exchange a magic link token for a session.

Field	Type	Required	Description
token	string	yes	The token from the sign-in or invitation link.

Cost

What this call was billed, itemized. Misses and errors bill nothing.

Field	Type	Required	Description
decision_usd	number	yes	Price of the decision. US dollars, up to 6 decimals.
vendor_usd	number	yes	Vendor pass-through charges (always 0 in v1). US dollars, up to 6 decimals.
total_usd	number	yes	Total billed for this call. US dollars, up to 6 decimals.

CreatedApiKey

A new API key with its secret (shown once).

Field	Type	Required	Description
id	string	yes	The key id.
project_id	string	yes	Project the key belongs to.
name	string	yes	Name.
environment	enum: “live”, “test”	yes	live or test.
prefix	string	yes	The key’s first characters, to recognize it.
scopes	array of enum: “decisions:write”, “index:read”, “outcomes:write”, “watches:manage”, “vendors:call”, “account:read”, “account:manage”, “keys:manage”	yes	Scopes granted.
status	enum: “active”, “rotating”, “revoked”, “expired”	yes	Lifecycle status.
rate_limit_per_minute	integer	yes	Requests per minute allowed.
daily_spend_cap_usd	number or null	yes	Daily spend cap, or null for none. US dollars, up to 6 decimals.
ip_allowlist	array of string	yes	CIDR blocks the key may be used from; empty means anywhere.
expires_at	string or null (date-time)	yes	Expiry, or null for none.
last_used_at	string or null (date-time)	yes	Last successful use, or null.
created_at	string (date-time)	yes	When the key was created.
secret	string	yes	The API key: vd_live_ or vd_test_ plus a base62 body. Shown once; store it now.

CreatedWatch

A new watch and its signing secret (shown once).

Field	Type	Required	Description
id	string	yes	The watch id.
project_id	string	yes	Project the watch belongs to.
icp_id	string	yes	ICP profile events are scored for.
webhook_url	string (uri)	yes	Delivery endpoint.
min_p	number	yes	Minimum relevant delivered.
types	array of enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	yes	Event types watched.
status	enum: “pending_verification”, “active”, “paused”, “deleted”	yes	Lifecycle status.
created_at	string (date-time)	yes	When the watch was created.
updated_at	string (date-time)	yes	When the watch last changed.
signing_secret	string	yes	Secret for verifying Verdict-Signature on deliveries. Shown once; store it now.

CreateIcpRequest

A new ICP profile.

Field	Type	Required	Description
name	string	yes	Short name, for example RIAs under $1B.
description	string	yes	Plain-text description of who you sell to and what you sell. At most 8192 bytes of UTF-8.
filters	IcpFilters	no	Optional structured filters that sharpen the plain-text profile.
filters.firm_types	array of enum: “operating_company”, “investment_adviser”, “broker_dealer”, “investment_fund”, “nonprofit”, “public_body”, “other”, “unknown”	no	Firm types to target.
filters.size_bands	array of enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”	no	Size bands to target.
filters.countries	array of string	no	Headquarters countries to target.
filters.exclude_countries	array of string	no	Headquarters countries to exclude.
filters.exclude_domains	array of string	no	Firms to exclude by domain (for example existing customers).
filters.event_types	array of enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	no	Event types that signal buying intent for this ICP.
project_id	string	no	Project to create the profile in; defaults to the key’s project.

CreateInviteRequest

Invite someone by email.

Field	Type	Required	Description
email	string (email)	yes	Who to invite.
role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	Role on accepting. Only an owner may invite an owner.

CreateKeyRequest

A new API key.

Field	Type	Required	Description
name	string	yes	Name, for example outbound-agent prod.
project_id	string	no	Project; defaults to the calling key’s project.
environment	enum: “live”, “test”	no	live (default) or test.
scopes	array of enum: “decisions:write”, “index:read”, “outcomes:write”, “watches:manage”, “vendors:call”, “account:read”, “account:manage”, “keys:manage”	no	Scopes; default decisions:write, index:read, outcomes:write.
expires_at	string (date-time)	no	Expiry; default none.
rate_limit_per_minute	integer	no	Requests per minute; default 600.
daily_spend_cap_usd	number	no	Daily spend cap; default none. US dollars, up to 6 decimals.
ip_allowlist	array of string (ipv4-cidr) or string (ipv6-cidr)	no	CIDR blocks the key may be used from; default anywhere.

CreateOutcomeRequest

An outcome for one decision.

Field	Type	Required	Description
decision_id	string	yes	The decision the outcome belongs to.
outcome	enum: “bounced”, “delivered”, “replied”, “interested”, “not_interested”, “meeting_booked”, “meeting_held”, “approved”, “skipped”, “reopened”, “converted” or string	yes	The outcome: a built-in type or custom:<slug>.
observed_at	string (date-time)	yes	When the outcome happened.
meta	object	no	Optional metadata: up to 20 keys of at most 64 characters, scalar values. No personal data.

CreateWatchRequest

A standing request for scored events, delivered by webhook.

Field	Type	Required	Description
icp_id	string	yes	Score events for this ICP profile.
webhook_url	string (uri)	yes	HTTPS endpoint that receives deliveries. Private and link-local addresses are refused; the URL must answer a challenge at registration.
min_p	number	yes	Deliver only events whose relevant is at least this.
types	array of enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	yes	Event types to watch.

Decision

A stored decision, exactly as it was returned; discriminated by decision.

Field	Type	Required	Description
id	string	no	The decision id. Report outcomes against it.
decision	enum: “qualify_firm”	no	The decision name.
version	enum: “2026-11-01”	no	API version that served the decision.
question_set_version	string (date)	no	Version (a date) of the question set that answered (spec 6.1).
model	enum: “jev”	no	Decision model that answered: always jev (ADR-0008).
p	number	no	Calibrated probability (spec 6.4). Always present.
answer	enum: “fit”, “not_fit”	no	fit or not_fit: p applied to your threshold.
reason_code	enum: “icp_type_and_size_match”, “icp_type_match_size_mismatch”, “icp_size_match_type_mismatch”, “icp_type_and_size_mismatch”, “icp_geography_mismatch”, “icp_exclusion_filter_match”, “firm_inactive”, “insufficient_firm_data”	no	Why, from the fixed qualify_firm reason-code enum.
reason	string	no	Short templated explanation of reason_code; never free text from a frontier model.
evidence	array of Evidence	no	Cited sources, with URLs and dates.
evidence[].source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”, “request”	yes	The index source cited, or request when the evidence is part of your own input.
evidence[].url	string or null (uri)	yes	Link to the cited record at the source; null when source is request.
evidence[].observed_at	string (date)	yes	Date the source reported the fact.
evidence[].label	string	no	Short description of what the evidence shows.
evidence[].pointer	string	no	JSON Pointer into your request body when source is request, for example /thread/2.
calibration	Calibration	no	How p was calibrated (spec 6.4).
calibration.basis	enum: “org”, “segment”, “global”	yes	org (your own outcomes), segment (your ICP’s segment) or global: how much to trust p.
calibration.n_outcomes	integer	yes	Outcomes behind the calibration map used.
calibration.threshold	number	yes	The threshold answer applied to p.
cost	Cost	no	What this call was billed, itemized. Misses and errors bill nothing.
cost.decision_usd	number	yes	Price of the decision. US dollars, up to 6 decimals.
cost.vendor_usd	number	yes	Vendor pass-through charges (always 0 in v1). US dollars, up to 6 decimals.
cost.total_usd	number	yes	Total billed for this call. US dollars, up to 6 decimals.
balance_usd	number	no	Balance after this call. US dollars, up to 6 decimals.
latency_ms	integer	no	Server-side latency of the call, in milliseconds.
created_at	string (date-time)	no	When the decision was made. Decisions are immutable.
fit	number	no	Probability the firm fits the ICP; equal to p.
firm	FirmSummary	no	A firm’s id, names, identifiers and public facts.
firm.id	string	yes	The firm id.
firm.name	string	yes	Canonical firm name.
firm.domain	string or null	yes	Primary web domain, if known.
firm.identifiers	object	yes	Registry identifiers, by kind.
firm.identifiers.lei	string	no	Legal Entity Identifier.
firm.identifiers.cik	string	no	SEC Central Index Key.
firm.identifiers.crd	string	no	CRD number.
firm.identifiers.companies_house	string	no	UK Companies House number.
firm.identifiers.wikidata	string	no	Wikidata item id.
firm.type	enum: “operating_company”, “investment_adviser”, “broker_dealer”, “investment_fund”, “nonprofit”, “public_body”, “other”, “unknown”	yes	Coarse firm type.
firm.size_band	enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”	yes	Employee-count size band.
firm.hq	object	yes	Headquarters location.
firm.hq.country	string or null	yes	ISO 3166-1 alpha-2 country.
firm.hq.region	string or null	yes	State, county or region, as the registry gives it.
firm.hq.city	string or null	yes	City.
firm.status	enum: “active”, “inactive”, “dissolved”, “unknown”, “merged”	yes	Registry status.
relevant	number	no	Probability the event matters for the ICP’s offer; equal to p.
act_now	number	no	Probability that now is the time to act on it.
window_days	integer or null	no	Days left to act, or null when there is no clear window.
event_id	string	no	The scored event (an inline event is stored and given an id).
people	array of object	no	The whole roster ranked best first, each with p.
people[].index	integer	yes	Zero-based position of the person in your roster.
people[].ref	string or null	yes	Your ref for the person, or null if you gave none.
people[].rank	integer	yes	Rank, 1 is best.
people[].p	number	yes	Calibrated probability that this is the right person to write to.
state	enum: “interested”, “meeting_requested”, “question”, “objection_price”, “objection_timing”, “objection_fit”, “not_decision_maker”, “referral”, “out_of_office”, “unsubscribe”, “bounce”, “wrong_person”, “other”	no	The most likely state of the thread.
next_action	enum: “reply”, “book_meeting”, “answer_question”, “handle_objection”, “forward_to_referral”, “find_other_contact”, “retry_later”, “unsubscribe”, “stop”, “escalate_to_human”, “none”	no	What the agent should do next.
send	number	no	Probability that sending now is right; equal to p.
hold_reason	enum: “upstream_decision_weak”, “upstream_decision_missing”, “inbox_health_degraded”, “daily_volume_limit”, “recently_contacted”, “message_issue”, “recipient_opted_out”, “low_confidence”, null	no	Why to hold, when answer is hold; null when answer is send.

Delivery

One webhook delivery of one scored event. Billed once, when delivered.

Field	Type	Required	Description
id	string	yes	The delivery id; also the id of the delivered payload.
watch_id	string	yes	The watch.
event_id	string	yes	The delivered event.
decision_id	string or null	yes	The score_signal decision behind it.
status	enum: “pending”, “retrying”, “delivered”, “failed”	yes	Delivery status.
attempts	integer	yes	Attempts so far.
last_attempt_at	string or null (date-time)	yes	Time of the last attempt.
last_response_status	integer or null	yes	HTTP status of the last attempt, if a response arrived.
next_attempt_at	string or null (date-time)	yes	Time of the next retry, while retrying.
delivered_at	string or null (date-time)	yes	When a 2xx was received.
created_at	string (date-time)	yes	When the delivery was queued.

Event

Something that happened to a firm, normalized to one schema; attributes are typed per type (one of filing, registration, officer_change, ownership_change, lei_change, address_change, fund_raise, insider_trade, patent_filing, litigation, news_mention, repo_activity, hiring_aggregate).

Field	Type	Required	Description
id	string	no	The event id.
firm_id	string	no	The firm the event happened to.
occurred_at	string (date-time)	no	When the event happened, per the source.
observed_at	string (date-time)	no	When Verdict ingested the event.
source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”	no	The index source.
source_url	string (uri)	no	Link to the event at the source.
confidence	number	no	Confidence in the event’s normalization and firm keying.
score	EventScore	no	The event’s score for the requested ICP, or null when read without icp_id.
score.decision_id	string	yes	The score_signal decision that produced this score (billed once).
score.icp_id	string	yes	The ICP profile the event was scored against.
score.relevant	number	yes	Calibrated probability that the event matters for the ICP’s offer.
score.act_now	number	yes	Calibrated probability that now is the time to act.
score.window_days	integer or null	yes	Days left to act on the event, or null when there is no clear window.
score.answer	enum: “relevant”, “not_relevant”	yes	relevant applied to the threshold.
score.reason_code	enum: “event_relevant_and_timely”, “event_relevant_but_stale”, “event_type_not_relevant”, “event_routine”, “firm_not_in_icp”, “event_low_confidence”, “event_superseded”, “insufficient_event_data”	yes	Why, as a score_signal reason code.
type	enum: “filing”	no	Event type filing.
attributes	object	no	Attributes of a filing event.
attributes.filing_type	enum: “sec_8k”, “sec_form_d”, “sec_form_4”, “sec_s1”, “sec_13f”, “sec_adv”	yes	The filing sub-type.
attributes.accession_number	string	no	SEC accession number.
attributes.items	array of string	no	8-K item numbers reported, for sec_8k.
attributes.title	string	no	Filing title or form description.
attributes.form	string	no	The form type exactly as the source lists it, for example 8-K/A or 13F-HR.
attributes.file_number	string	no	SEC file number, for example 333-299845.

EventScore

The event’s score for the requested ICP, or null when read without icp_id.

Field	Type	Required	Description
decision_id	string	yes	The score_signal decision that produced this score (billed once).
icp_id	string	yes	The ICP profile the event was scored against.
relevant	number	yes	Calibrated probability that the event matters for the ICP’s offer.
act_now	number	yes	Calibrated probability that now is the time to act.
window_days	integer or null	yes	Days left to act on the event, or null when there is no clear window.
answer	enum: “relevant”, “not_relevant”	yes	relevant applied to the threshold.
reason_code	enum: “event_relevant_and_timely”, “event_relevant_but_stale”, “event_type_not_relevant”, “event_routine”, “firm_not_in_icp”, “event_low_confidence”, “event_superseded”, “insufficient_event_data”	yes	Why, as a score_signal reason code.

Evidence

A cited source behind a decision.

Field	Type	Required	Description
source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”, “request”	yes	The index source cited, or request when the evidence is part of your own input.
url	string or null (uri)	yes	Link to the cited record at the source; null when source is request.
observed_at	string (date)	yes	Date the source reported the fact.
label	string	no	Short description of what the evidence shows.
pointer	string	no	JSON Pointer into your request body when source is request, for example /thread/2.

Firm

A canonical firm with its public facts and identifier crosswalk.

Field	Type	Required	Description
id	string	yes	The firm id.
name	string	yes	Canonical firm name.
domain	string or null	yes	Primary web domain, if known.
identifiers	object	yes	Registry identifiers, by kind.
identifiers.lei	string	no	Legal Entity Identifier.
identifiers.cik	string	no	SEC Central Index Key.
identifiers.crd	string	no	CRD number.
identifiers.companies_house	string	no	UK Companies House number.
identifiers.wikidata	string	no	Wikidata item id.
type	enum: “operating_company”, “investment_adviser”, “broker_dealer”, “investment_fund”, “nonprofit”, “public_body”, “other”, “unknown”	yes	Coarse firm type.
size_band	enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”	yes	Employee-count size band.
hq	object	yes	Headquarters location.
hq.country	string or null	yes	ISO 3166-1 alpha-2 country.
hq.region	string or null	yes	State, county or region, as the registry gives it.
hq.city	string or null	yes	City.
status	enum: “active”, “inactive”, “dissolved”, “unknown”, “merged”	yes	Registry status.
provisional	boolean	yes	True when the firm was created from an unresolved reference and awaits nightly reconciliation.
crosswalk	array of object	yes	Every known identifier, including name variants and secondary domains, with its source.
crosswalk[].kind	enum: “domain”, “lei”, “cik”, “crd”, “companies_house”, “wikidata”, “name_variant”	yes	Identifier kind.
crosswalk[].value	string	yes	Identifier value.
crosswalk[].source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”, “request”	yes	Source that reported the identifier: an index source, or request when it came from a caller’s reference (provisional firms).
crosswalk[].observed_at	string (date)	yes	Date the source last reported the identifier.
created_at	string (date-time)	yes	When the firm entered the index.
updated_at	string (date-time)	yes	When the firm’s record last changed.

FirmReference

A firm reference: exactly one of firm_id, domain, name (with an optional hint), lei, cik, crd or companies_house.

Field	Type	Required	Description
firm_id	string	no	A firm id from Verdict’s index.
domain	string	no	The firm’s web domain.
name	string	no	The firm’s legal or trading name.
hint	object	no	Optional country, city or domain to disambiguate the name.
hint.country	string	no	ISO 3166-1 alpha-2 country of the firm’s headquarters.
hint.city	string	no	City of the firm’s headquarters.
hint.domain	string	no	A domain the firm is known to use.
lei	string	no	The firm’s Legal Entity Identifier.
cik	string	no	The firm’s SEC Central Index Key.
crd	string	no	The firm’s CRD number.
companies_house	string	no	The firm’s UK Companies House number.

FirmSummary

A firm’s id, names, identifiers and public facts.

Field	Type	Required	Description
id	string	yes	The firm id.
name	string	yes	Canonical firm name.
domain	string or null	yes	Primary web domain, if known.
identifiers	object	yes	Registry identifiers, by kind.
identifiers.lei	string	no	Legal Entity Identifier.
identifiers.cik	string	no	SEC Central Index Key.
identifiers.crd	string	no	CRD number.
identifiers.companies_house	string	no	UK Companies House number.
identifiers.wikidata	string	no	Wikidata item id.
type	enum: “operating_company”, “investment_adviser”, “broker_dealer”, “investment_fund”, “nonprofit”, “public_body”, “other”, “unknown”	yes	Coarse firm type.
size_band	enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”	yes	Employee-count size band.
hq	object	yes	Headquarters location.
hq.country	string or null	yes	ISO 3166-1 alpha-2 country.
hq.region	string or null	yes	State, county or region, as the registry gives it.
hq.city	string or null	yes	City.
status	enum: “active”, “inactive”, “dissolved”, “unknown”, “merged”	yes	Registry status.

GithubOauthCallbackRequest

The query parameters GitHub appended to the console callback URL.

Field	Type	Required	Description
code	string	yes	The code GitHub returned.
state	string	yes	The state GitHub returned.

GithubOauthStartResponse

Where to send the browser for GitHub.

Field	Type	Required	Description
authorize_url	string (uri)	yes	GitHub’s authorization page; send the browser there.
expires_at	string (date-time)	yes	When the OAuth state in the URL expires.

Icp

An ICP profile: who you sell to and what you sell.

Field	Type	Required	Description
id	string	yes	The ICP profile id.
project_id	string	yes	Project the profile belongs to.
name	string	yes	Name.
description	string	yes	Plain-text description.
filters	IcpFilters	yes	Optional structured filters that sharpen the plain-text profile.
filters.firm_types	array of enum: “operating_company”, “investment_adviser”, “broker_dealer”, “investment_fund”, “nonprofit”, “public_body”, “other”, “unknown”	no	Firm types to target.
filters.size_bands	array of enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”	no	Size bands to target.
filters.countries	array of string	no	Headquarters countries to target.
filters.exclude_countries	array of string	no	Headquarters countries to exclude.
filters.exclude_domains	array of string	no	Firms to exclude by domain (for example existing customers).
filters.event_types	array of enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	no	Event types that signal buying intent for this ICP.
segment	object	yes	Calibration segment of the profile (spec 6.4).
segment.industry_group	string or null	yes	Industry group assigned at summarization.
segment.size_band	enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”, null	yes	Size band assigned at summarization.
summary_status	enum: “pending”, “ready”, “failed”	yes	Status of the one-time summarization.
thresholds	Thresholds	yes	Decision thresholds, one per decision.
thresholds.qualify_firm	object	yes	Threshold for qualify_firm.
thresholds.qualify_firm.value	number	yes	The threshold answer applies to p.
thresholds.qualify_firm.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.
thresholds.score_signal	object	yes	Threshold for score_signal.
thresholds.score_signal.value	number	yes	The threshold answer applies to p.
thresholds.score_signal.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.
thresholds.pick_person	object	yes	Threshold for pick_person.
thresholds.pick_person.value	number	yes	The threshold answer applies to p.
thresholds.pick_person.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.
thresholds.triage_reply	object	yes	Threshold for triage_reply.
thresholds.triage_reply.value	number	yes	The threshold answer applies to p.
thresholds.triage_reply.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.
thresholds.right_person	object	yes	Threshold for right_person.
thresholds.right_person.value	number	yes	The threshold answer applies to p.
thresholds.right_person.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.
thresholds.should_send	object	yes	Threshold for should_send.
thresholds.should_send.value	number	yes	The threshold answer applies to p.
thresholds.should_send.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.
created_at	string (date-time)	yes	When the profile was created.
updated_at	string (date-time)	yes	When the profile last changed.

IcpFilters

Optional structured filters that sharpen the plain-text profile.

Field	Type	Required	Description
firm_types	array of enum: “operating_company”, “investment_adviser”, “broker_dealer”, “investment_fund”, “nonprofit”, “public_body”, “other”, “unknown”	no	Firm types to target.
size_bands	array of enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”	no	Size bands to target.
countries	array of string	no	Headquarters countries to target.
exclude_countries	array of string	no	Headquarters countries to exclude.
exclude_domains	array of string	no	Firms to exclude by domain (for example existing customers).
event_types	array of enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	no	Event types that signal buying intent for this ICP.

InboxHealth

Inbox health you measure; Verdict never reads your inbox.

Field	Type	Required	Description
bounce_rate_7d	number	no	Share of sends that bounced over the last 7 days.
spam_complaint_rate_7d	number	no	Share of sends marked as spam over the last 7 days.
reply_rate_7d	number	no	Share of sends replied to over the last 7 days.
sent_today	integer	no	Messages sent from this inbox today.
daily_limit	integer	no	Your daily send limit for this inbox.
domain_age_days	integer	no	Age of the sending domain in days.

InlineEvent

An event the caller supplies, for events Verdict’s index does not hold.

Field	Type	Required	Description
type	enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	yes	Event type.
firm	FirmReference	yes	A firm reference: exactly one of firm_id, domain, name (with an optional hint), lei, cik, crd or companies_house.
firm.firm_id	string	no	A firm id from Verdict’s index.
firm.domain	string	no	The firm’s web domain.
firm.name	string	no	The firm’s legal or trading name.
firm.hint	object	no	Optional country, city or domain to disambiguate the name.
firm.hint.country	string	no	ISO 3166-1 alpha-2 country of the firm’s headquarters.
firm.hint.city	string	no	City of the firm’s headquarters.
firm.hint.domain	string	no	A domain the firm is known to use.
firm.lei	string	no	The firm’s Legal Entity Identifier.
firm.cik	string	no	The firm’s SEC Central Index Key.
firm.crd	string	no	The firm’s CRD number.
firm.companies_house	string	no	The firm’s UK Companies House number.
occurred_at	string (date-time)	yes	When the event happened.
title	string	no	One-line summary of the event.
description	string	no	What happened, in plain text. At most 8192 bytes of UTF-8.
source_url	string (uri)	no	Where the event was reported.

Invite

A pending invitation to join the organization.

Field	Type	Required	Description
id	string (uuid)	yes	The invitation id.
email	string (email)	yes	Who was invited.
role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	The role the invitee gets on accepting.
invited_by	string	yes	Who sent the invitation.
expires_at	string (date-time)	yes	When the invitation expires.
created_at	string (date-time)	yes	When it was sent.

LedgerEntry

One ledger entry.

Field	Type	Required	Description
id	string	yes	The ledger entry id.
kind	enum: “starter_credit”, “pack_credit”, “auto_topup_credit”, “promotional_credit”, “decision_debit”, “vendor_debit”, “refund”, “adjustment”	yes	Entry kind.
environment	enum: “live”, “test”	yes	live (cash) or test balance.
amount_usd	number	yes	Signed amount: credits positive, debits negative. US dollars, up to 6 decimals.
balance_after_usd	number	yes	Balance after the entry. US dollars, up to 6 decimals.
decision_id	string or null	yes	Decision billed, for debits.
pack_id	string or null	yes	Pack credited, for pack credits.
description	string	yes	Human description.
created_at	string (date-time)	yes	When the entry was written.

LimitsResponse

Limits that apply to the calling key.

Field	Type	Required	Description
rate_limit	object	yes	Rate limit of the calling key.
rate_limit.requests_per_minute	integer	yes	Requests per minute for this key.
rate_limit.burst	integer	yes	Burst allowance.
daily_spend_cap_usd	number or null	yes	Daily spend cap of the key, or null. US dollars, up to 6 decimals.
spent_today_usd	number	yes	Spent today (UTC) by the key. US dollars, up to 6 decimals.
request_limits	object	yes	Request size limits (spec 9.4).
request_limits.max_body_bytes	integer	yes	Maximum request body size.
request_limits.max_roster_entries	integer	yes	Maximum pick_person roster size.
request_limits.max_thread_messages	integer	yes	Maximum triage_reply thread length.
request_limits.max_message_bytes	integer	yes	Maximum bytes per message.
request_limits.max_page_limit	integer	yes	Maximum limit on list endpoints.
starter	object	yes	Starter allowance (spec 9.1): a card is required past $5 or 1,000 calls.
starter.card_required	boolean	yes	Whether a card is now required to keep calling.
starter.free_usd_remaining	number	yes	Starter credit left before a card is required. US dollars, up to 6 decimals.
starter.free_calls_remaining	integer	yes	Calls left before a card is required.

MagicLinkRequest

Ask for a sign-in link by email.

Field	Type	Required	Description
email	string (email)	yes	The email of an existing Verdict user.

MagicLinkResponse

A sign-in link was sent if the account exists.

Field	Type	Required	Description
status	enum: “sent”	yes	Always sent, whether or not the address has an account, so the endpoint does not reveal which emails are registered.
expires_at	string (date-time)	yes	When a link sent now expires.

Member

A member of the organization.

Field	Type	Required	Description
user_id	string	yes	The member’s user id.
email	string (email)	yes	The member’s email.
role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	The member’s role.
totp_enabled	boolean	yes	Whether the member has TOTP on.
joined_at	string (date-time)	yes	When the member joined.

MembersResponse

Members and pending invitations.

Field	Type	Required	Description
members	array of Member	yes	Current members, oldest first.
members[].user_id	string	yes	The member’s user id.
members[].email	string (email)	yes	The member’s email.
members[].role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	The member’s role.
members[].totp_enabled	boolean	yes	Whether the member has TOTP on.
members[].joined_at	string (date-time)	yes	When the member joined.
invites	array of Invite	yes	Pending invitations, newest first.
invites[].id	string (uuid)	yes	The invitation id.
invites[].email	string (email)	yes	Who was invited.
invites[].role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	The role the invitee gets on accepting.
invites[].invited_by	string	yes	Who sent the invitation.
invites[].expires_at	string (date-time)	yes	When the invitation expires.
invites[].created_at	string (date-time)	yes	When it was sent.

MeResponse

Who the calling key is.

Field	Type	Required	Description
org	object	yes	The calling key’s organization.
org.id	string	yes	Organization id.
org.name	string	yes	Organization name.
org.created_at	string (date-time)	yes	When the organization was created.
project	object	yes	The calling key’s project.
project.id	string	yes	Project id.
project.name	string	yes	Project name.
key	ApiKey	yes	An API key’s metadata.
key.id	string	yes	The key id.
key.project_id	string	yes	Project the key belongs to.
key.name	string	yes	Name.
key.environment	enum: “live”, “test”	yes	live or test.
key.prefix	string	yes	The key’s first characters, to recognize it.
key.scopes	array of enum: “decisions:write”, “index:read”, “outcomes:write”, “watches:manage”, “vendors:call”, “account:read”, “account:manage”, “keys:manage”	yes	Scopes granted.
key.status	enum: “active”, “rotating”, “revoked”, “expired”	yes	Lifecycle status.
key.rate_limit_per_minute	integer	yes	Requests per minute allowed.
key.daily_spend_cap_usd	number or null	yes	Daily spend cap, or null for none. US dollars, up to 6 decimals.
key.ip_allowlist	array of string	yes	CIDR blocks the key may be used from; empty means anywhere.
key.expires_at	string or null (date-time)	yes	Expiry, or null for none.
key.last_used_at	string or null (date-time)	yes	Last successful use, or null.
key.created_at	string (date-time)	yes	When the key was created.
api_version	enum: “2026-11-01”	yes	API version this key uses by default.

Outcome

A recorded outcome.

Field	Type	Required	Description
id	string	yes	The outcome id.
decision_id	string	yes	The decision it belongs to.
outcome	enum: “bounced”, “delivered”, “replied”, “interested”, “not_interested”, “meeting_booked”, “meeting_held”, “approved”, “skipped”, “reopened”, “converted” or string	yes	The outcome: a built-in type or custom:<slug>.
observed_at	string (date-time)	yes	When the outcome happened.
meta	object or null	yes	Optional metadata: up to 20 keys of at most 64 characters, scalar values. No personal data.
created_at	string (date-time)	yes	When Verdict recorded it.

PickPersonRequest

A roster of people at one firm, the ICP and an optional question.

Field	Type	Required	Description
roster	array of RosterEntry	yes	The people to rank, 1 to 50.
roster[].ref	string	no	Your own id for this person, echoed back in people.
roster[].name	string	yes	Full name.
roster[].title	string	yes	Job title.
roster[].seniority	enum: “owner”, “c_level”, “vp”, “director”, “manager”, “senior”, “entry”, “unknown”	no	Seniority, if known.
roster[].department	string	no	Department or function, for example Operations.
roster[].location	string	no	City or country.
roster[].tenure_months	integer	no	Months in the current role.
firm	FirmReference	no	A firm reference: exactly one of firm_id, domain, name (with an optional hint), lei, cik, crd or companies_house.
firm.firm_id	string	no	A firm id from Verdict’s index.
firm.domain	string	no	The firm’s web domain.
firm.name	string	no	The firm’s legal or trading name.
firm.hint	object	no	Optional country, city or domain to disambiguate the name.
firm.hint.country	string	no	ISO 3166-1 alpha-2 country of the firm’s headquarters.
firm.hint.city	string	no	City of the firm’s headquarters.
firm.hint.domain	string	no	A domain the firm is known to use.
firm.lei	string	no	The firm’s Legal Entity Identifier.
firm.cik	string	no	The firm’s SEC Central Index Key.
firm.crd	string	no	The firm’s CRD number.
firm.companies_house	string	no	The firm’s UK Companies House number.
icp_id	string	yes	The ICP profile to decide against.
question	string	no	Optional extra question, for example who owns trading operations?.

PickPersonResponse

The pick_person decision envelope.

Field	Type	Required	Description
id	string	yes	The decision id. Report outcomes against it.
decision	enum: “pick_person”	yes	The decision name.
version	enum: “2026-11-01”	yes	API version that served the decision.
question_set_version	string (date)	yes	Version (a date) of the question set that answered (spec 6.1).
model	enum: “jev”	yes	Decision model that answered: always jev (ADR-0008).
p	number	yes	Calibrated probability (spec 6.4). Always present.
answer	enum: “pick”, “no_pick”	yes	pick or no_pick: the top person’s p applied to your threshold.
reason_code	enum: “buyer_role_match”, “seniority_match”, “influencer_role_match”, “question_match”, “too_senior_for_offer”, “too_junior_for_offer”, “titles_ambiguous”, “no_strong_match”	yes	Why, from the fixed pick_person reason-code enum.
reason	string	yes	Short templated explanation of reason_code; never free text from a frontier model.
evidence	array of Evidence	yes	Cited sources, with URLs and dates.
evidence[].source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”, “request”	yes	The index source cited, or request when the evidence is part of your own input.
evidence[].url	string or null (uri)	yes	Link to the cited record at the source; null when source is request.
evidence[].observed_at	string (date)	yes	Date the source reported the fact.
evidence[].label	string	no	Short description of what the evidence shows.
evidence[].pointer	string	no	JSON Pointer into your request body when source is request, for example /thread/2.
calibration	Calibration	yes	How p was calibrated (spec 6.4).
calibration.basis	enum: “org”, “segment”, “global”	yes	org (your own outcomes), segment (your ICP’s segment) or global: how much to trust p.
calibration.n_outcomes	integer	yes	Outcomes behind the calibration map used.
calibration.threshold	number	yes	The threshold answer applied to p.
cost	Cost	yes	What this call was billed, itemized. Misses and errors bill nothing.
cost.decision_usd	number	yes	Price of the decision. US dollars, up to 6 decimals.
cost.vendor_usd	number	yes	Vendor pass-through charges (always 0 in v1). US dollars, up to 6 decimals.
cost.total_usd	number	yes	Total billed for this call. US dollars, up to 6 decimals.
balance_usd	number	yes	Balance after this call. US dollars, up to 6 decimals.
latency_ms	integer	yes	Server-side latency of the call, in milliseconds.
created_at	string (date-time)	yes	When the decision was made. Decisions are immutable.
people	array of object	yes	The whole roster ranked best first, each with p.
people[].index	integer	yes	Zero-based position of the person in your roster.
people[].ref	string or null	yes	Your ref for the person, or null if you gave none.
people[].rank	integer	yes	Rank, 1 is best.
people[].p	number	yes	Calibrated probability that this is the right person to write to.

Problem

An RFC 9457 problem-details error. Every error carries type and request_id. Errors are never billed.

Field	Type	Required	Description
type	enum: “invalid_request”, “unauthorized”, “forbidden_scope”, “not_found”, “insufficient_balance”, “max_cost_exceeded”, “rate_limited”, “idempotency_conflict”, “vendor_unavailable”, “decision_unavailable”, “internal”	yes	Stable error slug (a relative URI reference, RFC 9457). Branch on this, not on title or detail. invalid_request (400): The request is malformed, has unknown fields or breaks a size limit. unauthorized (401): The API key is missing, malformed, revoked or expired. forbidden_scope (403): The key lacks the scope this endpoint needs, or the resource belongs to another org. not_found (404): The resource does not exist in this organization. insufficient_balance (402): The balance cannot cover the call; top up. max_cost_exceeded (402): The call would cost more than X-Max-Cost-USD; nothing was spent. rate_limited (429): Too many requests; wait Retry-After seconds. idempotency_conflict (409): The Idempotency-Key was reused with a different request, or the first request is still running. vendor_unavailable (503): A vendor the call depends on is unavailable; nothing was billed. decision_unavailable (503): The decision model is temporarily unavailable or decisions are switched off; retry after Retry-After. Nothing was billed. internal (500): An unexpected server error; nothing was billed. Retry with the same Idempotency-Key.
title	string	yes	Short human summary of the error type.
status	integer	yes	The HTTP status code, repeated.
detail	string	yes	Human explanation of this occurrence.
instance	string	no	The request path that failed.
request_id	string	yes	The request id; also sent as X-Request-Id.
errors	array of object	no	Field-level issues, present on invalid_request.
errors[].path	string	yes	JSON Pointer (RFC 6901) to the offending field, or the header or query parameter name.
errors[].message	string	yes	What is wrong with the field.
required_usd	number	no	What the call would cost, in US dollars; present on 402 errors.
balance_usd	number	no	The current balance, in US dollars; present on insufficient_balance.
retry_after_seconds	integer	no	Seconds to wait before retrying; present on rate_limited (429) and on 503s (decision_unavailable, vendor_unavailable), equal to the Retry-After header.

QualifyFirmRequest

A firm reference and the ICP to qualify it against.

Field	Type	Required	Description
firm	FirmReference	yes	A firm reference: exactly one of firm_id, domain, name (with an optional hint), lei, cik, crd or companies_house.
firm.firm_id	string	no	A firm id from Verdict’s index.
firm.domain	string	no	The firm’s web domain.
firm.name	string	no	The firm’s legal or trading name.
firm.hint	object	no	Optional country, city or domain to disambiguate the name.
firm.hint.country	string	no	ISO 3166-1 alpha-2 country of the firm’s headquarters.
firm.hint.city	string	no	City of the firm’s headquarters.
firm.hint.domain	string	no	A domain the firm is known to use.
firm.lei	string	no	The firm’s Legal Entity Identifier.
firm.cik	string	no	The firm’s SEC Central Index Key.
firm.crd	string	no	The firm’s CRD number.
firm.companies_house	string	no	The firm’s UK Companies House number.
icp_id	string	yes	The ICP profile to decide against.

QualifyFirmResponse

The qualify_firm decision envelope.

Field	Type	Required	Description
id	string	yes	The decision id. Report outcomes against it.
decision	enum: “qualify_firm”	yes	The decision name.
version	enum: “2026-11-01”	yes	API version that served the decision.
question_set_version	string (date)	yes	Version (a date) of the question set that answered (spec 6.1).
model	enum: “jev”	yes	Decision model that answered: always jev (ADR-0008).
p	number	yes	Calibrated probability (spec 6.4). Always present.
answer	enum: “fit”, “not_fit”	yes	fit or not_fit: p applied to your threshold.
reason_code	enum: “icp_type_and_size_match”, “icp_type_match_size_mismatch”, “icp_size_match_type_mismatch”, “icp_type_and_size_mismatch”, “icp_geography_mismatch”, “icp_exclusion_filter_match”, “firm_inactive”, “insufficient_firm_data”	yes	Why, from the fixed qualify_firm reason-code enum.
reason	string	yes	Short templated explanation of reason_code; never free text from a frontier model.
evidence	array of Evidence	yes	Cited sources, with URLs and dates.
evidence[].source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”, “request”	yes	The index source cited, or request when the evidence is part of your own input.
evidence[].url	string or null (uri)	yes	Link to the cited record at the source; null when source is request.
evidence[].observed_at	string (date)	yes	Date the source reported the fact.
evidence[].label	string	no	Short description of what the evidence shows.
evidence[].pointer	string	no	JSON Pointer into your request body when source is request, for example /thread/2.
calibration	Calibration	yes	How p was calibrated (spec 6.4).
calibration.basis	enum: “org”, “segment”, “global”	yes	org (your own outcomes), segment (your ICP’s segment) or global: how much to trust p.
calibration.n_outcomes	integer	yes	Outcomes behind the calibration map used.
calibration.threshold	number	yes	The threshold answer applied to p.
cost	Cost	yes	What this call was billed, itemized. Misses and errors bill nothing.
cost.decision_usd	number	yes	Price of the decision. US dollars, up to 6 decimals.
cost.vendor_usd	number	yes	Vendor pass-through charges (always 0 in v1). US dollars, up to 6 decimals.
cost.total_usd	number	yes	Total billed for this call. US dollars, up to 6 decimals.
balance_usd	number	yes	Balance after this call. US dollars, up to 6 decimals.
latency_ms	integer	yes	Server-side latency of the call, in milliseconds.
created_at	string (date-time)	yes	When the decision was made. Decisions are immutable.
fit	number	yes	Probability the firm fits the ICP; equal to p.
firm	FirmSummary	yes	A firm’s id, names, identifiers and public facts.
firm.id	string	yes	The firm id.
firm.name	string	yes	Canonical firm name.
firm.domain	string or null	yes	Primary web domain, if known.
firm.identifiers	object	yes	Registry identifiers, by kind.
firm.identifiers.lei	string	no	Legal Entity Identifier.
firm.identifiers.cik	string	no	SEC Central Index Key.
firm.identifiers.crd	string	no	CRD number.
firm.identifiers.companies_house	string	no	UK Companies House number.
firm.identifiers.wikidata	string	no	Wikidata item id.
firm.type	enum: “operating_company”, “investment_adviser”, “broker_dealer”, “investment_fund”, “nonprofit”, “public_body”, “other”, “unknown”	yes	Coarse firm type.
firm.size_band	enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”	yes	Employee-count size band.
firm.hq	object	yes	Headquarters location.
firm.hq.country	string or null	yes	ISO 3166-1 alpha-2 country.
firm.hq.region	string or null	yes	State, county or region, as the registry gives it.
firm.hq.city	string or null	yes	City.
firm.status	enum: “active”, “inactive”, “dissolved”, “unknown”, “merged”	yes	Registry status.

ResolveFirmResponse

The resolved firm and how it was matched.

Field	Type	Required	Description
firm	Firm	yes	A canonical firm with its public facts and identifier crosswalk.
firm.id	string	yes	The firm id.
firm.name	string	yes	Canonical firm name.
firm.domain	string or null	yes	Primary web domain, if known.
firm.identifiers	object	yes	Registry identifiers, by kind.
firm.identifiers.lei	string	no	Legal Entity Identifier.
firm.identifiers.cik	string	no	SEC Central Index Key.
firm.identifiers.crd	string	no	CRD number.
firm.identifiers.companies_house	string	no	UK Companies House number.
firm.identifiers.wikidata	string	no	Wikidata item id.
firm.type	enum: “operating_company”, “investment_adviser”, “broker_dealer”, “investment_fund”, “nonprofit”, “public_body”, “other”, “unknown”	yes	Coarse firm type.
firm.size_band	enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”	yes	Employee-count size band.
firm.hq	object	yes	Headquarters location.
firm.hq.country	string or null	yes	ISO 3166-1 alpha-2 country.
firm.hq.region	string or null	yes	State, county or region, as the registry gives it.
firm.hq.city	string or null	yes	City.
firm.status	enum: “active”, “inactive”, “dissolved”, “unknown”, “merged”	yes	Registry status.
firm.provisional	boolean	yes	True when the firm was created from an unresolved reference and awaits nightly reconciliation.
firm.crosswalk	array of object	yes	Every known identifier, including name variants and secondary domains, with its source.
firm.crosswalk[].kind	enum: “domain”, “lei”, “cik”, “crd”, “companies_house”, “wikidata”, “name_variant”	yes	Identifier kind.
firm.crosswalk[].value	string	yes	Identifier value.
firm.crosswalk[].source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”, “request”	yes	Source that reported the identifier: an index source, or request when it came from a caller’s reference (provisional firms).
firm.crosswalk[].observed_at	string (date)	yes	Date the source last reported the identifier.
firm.created_at	string (date-time)	yes	When the firm entered the index.
firm.updated_at	string (date-time)	yes	When the firm’s record last changed.
matched_on	enum: “identifier”, “domain”, “name_and_country”, “match_decision”, “provisional”	yes	How the reference was matched.

RightPersonRequest

A candidate contact and the ICP.

Field	Type	Required	Description
candidate	CandidateContact	yes	One candidate contact. LinkedIn-sourced data is not accepted.
candidate.name	string	no	Full name.
candidate.title	string	yes	Job title.
candidate.seniority	enum: “owner”, “c_level”, “vp”, “director”, “manager”, “senior”, “entry”, “unknown”	no	Seniority, if known.
candidate.department	string	no	Department or function.
candidate.email	string (email)	no	Work email, if known.
candidate.firm	FirmReference	no	A firm reference: exactly one of firm_id, domain, name (with an optional hint), lei, cik, crd or companies_house.
candidate.firm.firm_id	string	no	A firm id from Verdict’s index.
candidate.firm.domain	string	no	The firm’s web domain.
candidate.firm.name	string	no	The firm’s legal or trading name.
candidate.firm.hint	object	no	Optional country, city or domain to disambiguate the name.
candidate.firm.lei	string	no	The firm’s Legal Entity Identifier.
candidate.firm.cik	string	no	The firm’s SEC Central Index Key.
candidate.firm.crd	string	no	The firm’s CRD number.
candidate.firm.companies_house	string	no	The firm’s UK Companies House number.
candidate.title_observed_at	string (date-time)	no	When you last saw this title, to judge staleness.
icp_id	string	yes	The ICP profile to decide against.

RightPersonResponse

The right_person decision envelope.

Field	Type	Required	Description
id	string	yes	The decision id. Report outcomes against it.
decision	enum: “right_person”	yes	The decision name.
version	enum: “2026-11-01”	yes	API version that served the decision.
question_set_version	string (date)	yes	Version (a date) of the question set that answered (spec 6.1).
model	enum: “jev”	yes	Decision model that answered: always jev (ADR-0008).
p	number	yes	Calibrated probability (spec 6.4). Always present.
answer	enum: “right_person”, “not_right_person”	yes	right_person or not_right_person: p applied to your threshold.
reason_code	enum: “title_and_seniority_match”, “title_match_seniority_mismatch”, “seniority_match_title_mismatch”, “department_mismatch”, “firm_not_in_icp”, “candidate_data_stale”, “insufficient_candidate_data”	yes	Why, from the fixed right_person reason-code enum.
reason	string	yes	Short templated explanation of reason_code; never free text from a frontier model.
evidence	array of Evidence	yes	Cited sources, with URLs and dates.
evidence[].source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”, “request”	yes	The index source cited, or request when the evidence is part of your own input.
evidence[].url	string or null (uri)	yes	Link to the cited record at the source; null when source is request.
evidence[].observed_at	string (date)	yes	Date the source reported the fact.
evidence[].label	string	no	Short description of what the evidence shows.
evidence[].pointer	string	no	JSON Pointer into your request body when source is request, for example /thread/2.
calibration	Calibration	yes	How p was calibrated (spec 6.4).
calibration.basis	enum: “org”, “segment”, “global”	yes	org (your own outcomes), segment (your ICP’s segment) or global: how much to trust p.
calibration.n_outcomes	integer	yes	Outcomes behind the calibration map used.
calibration.threshold	number	yes	The threshold answer applied to p.
cost	Cost	yes	What this call was billed, itemized. Misses and errors bill nothing.
cost.decision_usd	number	yes	Price of the decision. US dollars, up to 6 decimals.
cost.vendor_usd	number	yes	Vendor pass-through charges (always 0 in v1). US dollars, up to 6 decimals.
cost.total_usd	number	yes	Total billed for this call. US dollars, up to 6 decimals.
balance_usd	number	yes	Balance after this call. US dollars, up to 6 decimals.
latency_ms	integer	yes	Server-side latency of the call, in milliseconds.
created_at	string (date-time)	yes	When the decision was made. Decisions are immutable.

RosterEntry

One person at the firm. LinkedIn-sourced data is not accepted.

Field	Type	Required	Description
ref	string	no	Your own id for this person, echoed back in people.
name	string	yes	Full name.
title	string	yes	Job title.
seniority	enum: “owner”, “c_level”, “vp”, “director”, “manager”, “senior”, “entry”, “unknown”	no	Seniority, if known.
department	string	no	Department or function, for example Operations.
location	string	no	City or country.
tenure_months	integer	no	Months in the current role.

RotateKeyRequest

Rotation options.

Field	Type	Required	Description
grace_period_hours	integer	no	Hours the old key stays valid; default 24.

RotateKeyResponse

The replacement key (secret shown once) and the old key’s grace window.

Field	Type	Required	Description
key	CreatedApiKey	yes	A new API key with its secret (shown once).
key.id	string	yes	The key id.
key.project_id	string	yes	Project the key belongs to.
key.name	string	yes	Name.
key.environment	enum: “live”, “test”	yes	live or test.
key.prefix	string	yes	The key’s first characters, to recognize it.
key.scopes	array of enum: “decisions:write”, “index:read”, “outcomes:write”, “watches:manage”, “vendors:call”, “account:read”, “account:manage”, “keys:manage”	yes	Scopes granted.
key.status	enum: “active”, “rotating”, “revoked”, “expired”	yes	Lifecycle status.
key.rate_limit_per_minute	integer	yes	Requests per minute allowed.
key.daily_spend_cap_usd	number or null	yes	Daily spend cap, or null for none. US dollars, up to 6 decimals.
key.ip_allowlist	array of string	yes	CIDR blocks the key may be used from; empty means anywhere.
key.expires_at	string or null (date-time)	yes	Expiry, or null for none.
key.last_used_at	string or null (date-time)	yes	Last successful use, or null.
key.created_at	string (date-time)	yes	When the key was created.
key.secret	string	yes	The API key: vd_live_ or vd_test_ plus a base62 body. Shown once; store it now.
previous_key	object	yes	The old key and the end of its grace window.
previous_key.id	string	yes	The rotated key.
previous_key.valid_until	string (date-time)	yes	When the old key stops working.

ScoredEventDelivery

A scored event delivered to a watch.

Field	Type	Required	Description
id	string	yes	Delivery id; dedupe on it, retries reuse it.
type	enum: “event.scored”	yes	Payload type.
created_at	string (date-time)	yes	When the delivery was created.
watch_id	string	yes	The watch.
event	Event	yes	Something that happened to a firm, normalized to one schema; attributes are typed per type (one of filing, registration, officer_change, ownership_change, lei_change, address_change, fund_raise, insider_trade, patent_filing, litigation, news_mention, repo_activity, hiring_aggregate).
event.id	string	no	The event id.
event.firm_id	string	no	The firm the event happened to.
event.occurred_at	string (date-time)	no	When the event happened, per the source.
event.observed_at	string (date-time)	no	When Verdict ingested the event.
event.source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”	no	The index source.
event.source_url	string (uri)	no	Link to the event at the source.
event.confidence	number	no	Confidence in the event’s normalization and firm keying.
event.score	EventScore	no	The event’s score for the requested ICP, or null when read without icp_id.
event.score.decision_id	string	yes	The score_signal decision that produced this score (billed once).
event.score.icp_id	string	yes	The ICP profile the event was scored against.
event.score.relevant	number	yes	Calibrated probability that the event matters for the ICP’s offer.
event.score.act_now	number	yes	Calibrated probability that now is the time to act.
event.score.window_days	integer or null	yes	Days left to act on the event, or null when there is no clear window.
event.score.answer	enum: “relevant”, “not_relevant”	yes	relevant applied to the threshold.
event.score.reason_code	enum: “event_relevant_and_timely”, “event_relevant_but_stale”, “event_type_not_relevant”, “event_routine”, “firm_not_in_icp”, “event_low_confidence”, “event_superseded”, “insufficient_event_data”	yes	Why, as a score_signal reason code.
event.type	enum: “filing”	no	Event type filing.
event.attributes	object	no	Attributes of a filing event.
event.attributes.filing_type	enum: “sec_8k”, “sec_form_d”, “sec_form_4”, “sec_s1”, “sec_13f”, “sec_adv”	yes	The filing sub-type.
event.attributes.accession_number	string	no	SEC accession number.
event.attributes.items	array of string	no	8-K item numbers reported, for sec_8k.
event.attributes.title	string	no	Filing title or form description.
event.attributes.form	string	no	The form type exactly as the source lists it, for example 8-K/A or 13F-HR.
event.attributes.file_number	string	no	SEC file number, for example 333-299845.
score	EventScore and any	yes
score.decision_id	string	yes	The score_signal decision that produced this score (billed once).
score.icp_id	string	yes	The ICP profile the event was scored against.
score.relevant	number	yes	Calibrated probability that the event matters for the ICP’s offer.
score.act_now	number	yes	Calibrated probability that now is the time to act.
score.window_days	integer or null	yes	Days left to act on the event, or null when there is no clear window.
score.answer	enum: “relevant”, “not_relevant”	yes	relevant applied to the threshold.
score.reason_code	enum: “event_relevant_and_timely”, “event_relevant_but_stale”, “event_type_not_relevant”, “event_routine”, “firm_not_in_icp”, “event_low_confidence”, “event_superseded”, “insufficient_event_data”	yes	Why, as a score_signal reason code.

ScoreSignalRequest

An event_id from the index, or an inline event, and the ICP to score it for.

Field	Type	Required	Description
event_id	string	no	An event from the index.
icp_id	string	no	The ICP profile to decide against.
event	InlineEvent	no	An event the caller supplies, for events Verdict’s index does not hold.
event.type	enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	yes	Event type.
event.firm	FirmReference	yes	A firm reference: exactly one of firm_id, domain, name (with an optional hint), lei, cik, crd or companies_house.
event.firm.firm_id	string	no	A firm id from Verdict’s index.
event.firm.domain	string	no	The firm’s web domain.
event.firm.name	string	no	The firm’s legal or trading name.
event.firm.hint	object	no	Optional country, city or domain to disambiguate the name.
event.firm.lei	string	no	The firm’s Legal Entity Identifier.
event.firm.cik	string	no	The firm’s SEC Central Index Key.
event.firm.crd	string	no	The firm’s CRD number.
event.firm.companies_house	string	no	The firm’s UK Companies House number.
event.occurred_at	string (date-time)	yes	When the event happened.
event.title	string	no	One-line summary of the event.
event.description	string	no	What happened, in plain text. At most 8192 bytes of UTF-8.
event.source_url	string (uri)	no	Where the event was reported.

ScoreSignalResponse

The score_signal decision envelope.

Field	Type	Required	Description
id	string	yes	The decision id. Report outcomes against it.
decision	enum: “score_signal”	yes	The decision name.
version	enum: “2026-11-01”	yes	API version that served the decision.
question_set_version	string (date)	yes	Version (a date) of the question set that answered (spec 6.1).
model	enum: “jev”	yes	Decision model that answered: always jev (ADR-0008).
p	number	yes	Calibrated probability (spec 6.4). Always present.
answer	enum: “relevant”, “not_relevant”	yes	relevant or not_relevant: p applied to your threshold.
reason_code	enum: “event_relevant_and_timely”, “event_relevant_but_stale”, “event_type_not_relevant”, “event_routine”, “firm_not_in_icp”, “event_low_confidence”, “event_superseded”, “insufficient_event_data”	yes	Why, from the fixed score_signal reason-code enum.
reason	string	yes	Short templated explanation of reason_code; never free text from a frontier model.
evidence	array of Evidence	yes	Cited sources, with URLs and dates.
evidence[].source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”, “request”	yes	The index source cited, or request when the evidence is part of your own input.
evidence[].url	string or null (uri)	yes	Link to the cited record at the source; null when source is request.
evidence[].observed_at	string (date)	yes	Date the source reported the fact.
evidence[].label	string	no	Short description of what the evidence shows.
evidence[].pointer	string	no	JSON Pointer into your request body when source is request, for example /thread/2.
calibration	Calibration	yes	How p was calibrated (spec 6.4).
calibration.basis	enum: “org”, “segment”, “global”	yes	org (your own outcomes), segment (your ICP’s segment) or global: how much to trust p.
calibration.n_outcomes	integer	yes	Outcomes behind the calibration map used.
calibration.threshold	number	yes	The threshold answer applied to p.
cost	Cost	yes	What this call was billed, itemized. Misses and errors bill nothing.
cost.decision_usd	number	yes	Price of the decision. US dollars, up to 6 decimals.
cost.vendor_usd	number	yes	Vendor pass-through charges (always 0 in v1). US dollars, up to 6 decimals.
cost.total_usd	number	yes	Total billed for this call. US dollars, up to 6 decimals.
balance_usd	number	yes	Balance after this call. US dollars, up to 6 decimals.
latency_ms	integer	yes	Server-side latency of the call, in milliseconds.
created_at	string (date-time)	yes	When the decision was made. Decisions are immutable.
relevant	number	yes	Probability the event matters for the ICP’s offer; equal to p.
act_now	number	yes	Probability that now is the time to act on it.
window_days	integer or null	yes	Days left to act, or null when there is no clear window.
event_id	string	yes	The scored event (an inline event is stored and given an id).
firm	FirmSummary	yes	A firm’s id, names, identifiers and public facts.
firm.id	string	yes	The firm id.
firm.name	string	yes	Canonical firm name.
firm.domain	string or null	yes	Primary web domain, if known.
firm.identifiers	object	yes	Registry identifiers, by kind.
firm.identifiers.lei	string	no	Legal Entity Identifier.
firm.identifiers.cik	string	no	SEC Central Index Key.
firm.identifiers.crd	string	no	CRD number.
firm.identifiers.companies_house	string	no	UK Companies House number.
firm.identifiers.wikidata	string	no	Wikidata item id.
firm.type	enum: “operating_company”, “investment_adviser”, “broker_dealer”, “investment_fund”, “nonprofit”, “public_body”, “other”, “unknown”	yes	Coarse firm type.
firm.size_band	enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”	yes	Employee-count size band.
firm.hq	object	yes	Headquarters location.
firm.hq.country	string or null	yes	ISO 3166-1 alpha-2 country.
firm.hq.region	string or null	yes	State, county or region, as the registry gives it.
firm.hq.city	string or null	yes	City.
firm.status	enum: “active”, “inactive”, “dissolved”, “unknown”, “merged”	yes	Registry status.

ShouldSendRequest

A prepared message, the decisions behind it, inbox health and the ICP.

Field	Type	Required	Description
message	object	yes	The prepared message.
message.channel	enum: “email”, “other”	yes	Channel the message will go out on.
message.subject	string	no	Subject line.
message.body	string	yes	Plain-text body as it will be sent. At most 8192 bytes of UTF-8.
decision_ids	array of string	yes	The decisions behind the message (for example qualify_firm and pick_person), 1 to 10.
inbox_health	InboxHealth	yes	Inbox health you measure; Verdict never reads your inbox.
inbox_health.bounce_rate_7d	number	no	Share of sends that bounced over the last 7 days.
inbox_health.spam_complaint_rate_7d	number	no	Share of sends marked as spam over the last 7 days.
inbox_health.reply_rate_7d	number	no	Share of sends replied to over the last 7 days.
inbox_health.sent_today	integer	no	Messages sent from this inbox today.
inbox_health.daily_limit	integer	no	Your daily send limit for this inbox.
inbox_health.domain_age_days	integer	no	Age of the sending domain in days.
recipient	object	no	Optional contact history of the recipient.
recipient.last_contacted_at	string (date-time)	no	When you last wrote to this recipient.
recipient.touches_30d	integer	no	Messages sent to this recipient in 30 days.
icp_id	string	yes	The ICP profile to decide against.

ShouldSendResponse

The should_send decision envelope.

Field	Type	Required	Description
id	string	yes	The decision id. Report outcomes against it.
decision	enum: “should_send”	yes	The decision name.
version	enum: “2026-11-01”	yes	API version that served the decision.
question_set_version	string (date)	yes	Version (a date) of the question set that answered (spec 6.1).
model	enum: “jev”	yes	Decision model that answered: always jev (ADR-0008).
p	number	yes	Calibrated probability (spec 6.4). Always present.
answer	enum: “send”, “hold”	yes	send or hold: p applied to your threshold.
reason_code	enum: “all_checks_passed”, “upstream_decision_below_threshold”, “upstream_decision_missing”, “inbox_health_degraded”, “daily_volume_limit_reached”, “recipient_recently_contacted”, “message_quality_issue”, “recipient_opted_out”	yes	Why, from the fixed should_send reason-code enum.
reason	string	yes	Short templated explanation of reason_code; never free text from a frontier model.
evidence	array of Evidence	yes	Cited sources, with URLs and dates.
evidence[].source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”, “request”	yes	The index source cited, or request when the evidence is part of your own input.
evidence[].url	string or null (uri)	yes	Link to the cited record at the source; null when source is request.
evidence[].observed_at	string (date)	yes	Date the source reported the fact.
evidence[].label	string	no	Short description of what the evidence shows.
evidence[].pointer	string	no	JSON Pointer into your request body when source is request, for example /thread/2.
calibration	Calibration	yes	How p was calibrated (spec 6.4).
calibration.basis	enum: “org”, “segment”, “global”	yes	org (your own outcomes), segment (your ICP’s segment) or global: how much to trust p.
calibration.n_outcomes	integer	yes	Outcomes behind the calibration map used.
calibration.threshold	number	yes	The threshold answer applied to p.
cost	Cost	yes	What this call was billed, itemized. Misses and errors bill nothing.
cost.decision_usd	number	yes	Price of the decision. US dollars, up to 6 decimals.
cost.vendor_usd	number	yes	Vendor pass-through charges (always 0 in v1). US dollars, up to 6 decimals.
cost.total_usd	number	yes	Total billed for this call. US dollars, up to 6 decimals.
balance_usd	number	yes	Balance after this call. US dollars, up to 6 decimals.
latency_ms	integer	yes	Server-side latency of the call, in milliseconds.
created_at	string (date-time)	yes	When the decision was made. Decisions are immutable.
send	number	yes	Probability that sending now is right; equal to p.
hold_reason	enum: “upstream_decision_weak”, “upstream_decision_missing”, “inbox_health_degraded”, “daily_volume_limit”, “recently_contacted”, “message_issue”, “recipient_opted_out”, “low_confidence”, null	yes	Why to hold, when answer is hold; null when answer is send.

SignOutResponse

The session was revoked and the cookie cleared.

Field	Type	Required	Description
status	enum: “signed_out”	yes	The session was revoked.

SignupRequest

Start sign-up with an email address.

Field	Type	Required	Description
email	string (email)	yes	Work email. A verification link is sent to it; disposable domains are refused.
org_name	string	no	Organization name; defaults to the email’s domain.

SignupResponse

Sign-up accepted; verify the email to get a key.

Field	Type	Required	Description
status	enum: “verification_sent”	yes	A verification email was sent.
email	string (email)	yes	The address it was sent to.
expires_at	string (date-time)	yes	When the verification link expires.

Source

An open-licensed source of Verdict’s index.

Field	Type	Required	Description
id	string	yes	The source id.
source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”	yes	Stable source slug, as cited in evidence[].source.
name	string	yes	Human name.
phase	integer	yes	Release phase that ships the source.
license	object	yes	The source’s license.
license.kind	enum: “public_domain”, “cc0”, “ogl_v3”, “cc_by_4_0”, “cc_by_3_0_au”	yes	License kind.
license.name	string	yes	License name.
license.url	string (uri)	yes	License text.
license.attribution	string or null	yes	Attribution text to show when you display the data, if required.
refresh_cadence	string	yes	How often Verdict refreshes it, for example daily.
rate_limit	string or null	yes	The source’s fair-access limit Verdict observes.
last_successful_run	object or null	yes	Latest successful ingestion, or null if none yet.
last_successful_run.id	string	yes	The run id.
last_successful_run.status	enum: “running”, “succeeded”, “partial”, “failed”	yes	Run status.
last_successful_run.started_at	string (date-time)	yes	When the run started.
last_successful_run.finished_at	string or null (date-time)	yes	When the run finished.
last_successful_run.events_upserted	integer	yes	Events inserted or updated.
last_run	object or null	yes	Latest ingestion run of any status (it may still be running or have failed), or null if none yet.
last_run.id	string	yes	The run id.
last_run.status	enum: “running”, “succeeded”, “partial”, “failed”	yes	Run status.
last_run.started_at	string (date-time)	yes	When the run started.
last_run.finished_at	string or null (date-time)	yes	When the run finished.
last_run.events_upserted	integer	yes	Events inserted or updated.
freshness_seconds	integer or null	yes	Seconds since the latest successful run finished: how fresh this source’s data is. null if it has never succeeded.

StripeWebhookBody

A Stripe event object (id evt_..., type, data.object), exactly as Stripe sends it. Its shape is defined by Stripe.

Type: object.

StripeWebhookReceipt

Acknowledgement of a Stripe event.

Field	Type	Required	Description
received	enum: true	yes	The event was verified and recorded.
duplicate	boolean	yes	True when this Stripe event id was already recorded; nothing changed.

ThreadMessage

One message of a thread, oldest first.

Field	Type	Required	Description
role	enum: “sender”, “prospect”, “system”	yes	Who wrote the message.
text	string	yes	Plain-text body of the message. At most 8192 bytes of UTF-8.
sent_at	string (date-time)	yes	When the message was sent.

Thresholds

Decision thresholds, one per decision.

Field	Type	Required	Description
qualify_firm	object	yes	Threshold for qualify_firm.
qualify_firm.value	number	yes	The threshold answer applies to p.
qualify_firm.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.
score_signal	object	yes	Threshold for score_signal.
score_signal.value	number	yes	The threshold answer applies to p.
score_signal.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.
pick_person	object	yes	Threshold for pick_person.
pick_person.value	number	yes	The threshold answer applies to p.
pick_person.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.
triage_reply	object	yes	Threshold for triage_reply.
triage_reply.value	number	yes	The threshold answer applies to p.
triage_reply.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.
right_person	object	yes	Threshold for right_person.
right_person.value	number	yes	The threshold answer applies to p.
right_person.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.
should_send	object	yes	Threshold for should_send.
should_send.value	number	yes	The threshold answer applies to p.
should_send.source	enum: “calibrated”, “custom”	yes	Calibrated default or your own value.

TopupRequest

The pack to buy.

Field	Type	Required	Description
pack_usd	enum: 20 or enum: 50 or enum: 200	yes	Pack to buy: 20, 50 or 200 US dollars.

TopupResponse

A pending pack purchase with its Checkout URL.

Field	Type	Required	Description
id	string	yes	The pack purchase id.
pack_usd	enum: 20 or enum: 50 or enum: 200	yes	Pack size.
status	enum: “pending”, “completed”, “expired”, “failed”	yes	Purchase status.
checkout_url	string (uri)	yes	Stripe Checkout URL; open it to pay. The balance is credited when Stripe confirms payment.
expires_at	string (date-time)	yes	When the Checkout session expires.

TotpCodeRequest

A current TOTP code.

Field	Type	Required	Description
code	string	yes	The six-digit code from the authenticator app.

TotpEnrolResponse

A pending TOTP secret; it is active once a code is verified.

Field	Type	Required	Description
secret	string	yes	The base32 TOTP secret (shown once). Add it to an authenticator app, then confirm with a code.
otpauth_uri	string	yes	The same secret as an otpauth:// URI, to render as a QR code.

TotpStatusResponse

The user’s TOTP state after the call.

Field	Type	Required	Description
totp_enabled	boolean	yes	Whether TOTP is now on for the user.
mfa_verified	boolean	yes	Whether this session has now passed TOTP.

TriageReplyRequest

A reply thread and optional context.

Field	Type	Required	Description
thread	array of ThreadMessage	yes	The thread, oldest first, 1 to 40 messages; the last is the reply to triage.
thread[].role	enum: “sender”, “prospect”, “system”	yes	Who wrote the message.
thread[].text	string	yes	Plain-text body of the message. At most 8192 bytes of UTF-8.
thread[].sent_at	string (date-time)	yes	When the message was sent.
context	object	no	Optional context.
context.decision_id	string	no	The decision behind the original send.
context.notes	string	no	Short notes on what was offered. At most 2000 bytes of UTF-8.
icp_id	string	no	Optional ICP profile, for calibration by segment.

TriageReplyResponse

The triage_reply decision envelope.

Field	Type	Required	Description
id	string	yes	The decision id. Report outcomes against it.
decision	enum: “triage_reply”	yes	The decision name.
version	enum: “2026-11-01”	yes	API version that served the decision.
question_set_version	string (date)	yes	Version (a date) of the question set that answered (spec 6.1).
model	enum: “jev”	yes	Decision model that answered: always jev (ADR-0008).
p	number	yes	Calibrated probability (spec 6.4). Always present.
answer	enum: “interested”, “meeting_requested”, “question”, “objection_price”, “objection_timing”, “objection_fit”, “not_decision_maker”, “referral”, “out_of_office”, “unsubscribe”, “bounce”, “wrong_person”, “other”, “needs_review”	yes	The state when p is at or above your threshold, otherwise needs_review.
reason_code	enum: “explicit_positive_intent”, “explicit_meeting_request”, “explicit_question”, “explicit_objection”, “explicit_opt_out”, “redirect_to_other_person”, “auto_reply_detected”, “delivery_failure_detected”, “ambiguous_reply”, “thread_too_short”	yes	Why, from the fixed triage_reply reason-code enum.
reason	string	yes	Short templated explanation of reason_code; never free text from a frontier model.
evidence	array of Evidence	yes	Cited sources, with URLs and dates.
evidence[].source	enum: “sec_edgar”, “gleif”, “companies_house”, “wikidata”, “request”	yes	The index source cited, or request when the evidence is part of your own input.
evidence[].url	string or null (uri)	yes	Link to the cited record at the source; null when source is request.
evidence[].observed_at	string (date)	yes	Date the source reported the fact.
evidence[].label	string	no	Short description of what the evidence shows.
evidence[].pointer	string	no	JSON Pointer into your request body when source is request, for example /thread/2.
calibration	Calibration	yes	How p was calibrated (spec 6.4).
calibration.basis	enum: “org”, “segment”, “global”	yes	org (your own outcomes), segment (your ICP’s segment) or global: how much to trust p.
calibration.n_outcomes	integer	yes	Outcomes behind the calibration map used.
calibration.threshold	number	yes	The threshold answer applied to p.
cost	Cost	yes	What this call was billed, itemized. Misses and errors bill nothing.
cost.decision_usd	number	yes	Price of the decision. US dollars, up to 6 decimals.
cost.vendor_usd	number	yes	Vendor pass-through charges (always 0 in v1). US dollars, up to 6 decimals.
cost.total_usd	number	yes	Total billed for this call. US dollars, up to 6 decimals.
balance_usd	number	yes	Balance after this call. US dollars, up to 6 decimals.
latency_ms	integer	yes	Server-side latency of the call, in milliseconds.
created_at	string (date-time)	yes	When the decision was made. Decisions are immutable.
state	enum: “interested”, “meeting_requested”, “question”, “objection_price”, “objection_timing”, “objection_fit”, “not_decision_maker”, “referral”, “out_of_office”, “unsubscribe”, “bounce”, “wrong_person”, “other”	yes	The most likely state of the thread.
next_action	enum: “reply”, “book_meeting”, “answer_question”, “handle_objection”, “forward_to_referral”, “find_other_contact”, “retry_later”, “unsubscribe”, “stop”, “escalate_to_human”, “none”	yes	What the agent should do next.

UpdateIcpRequest

Fields of an ICP profile to change.

Field	Type	Required	Description
name	string	no	New name.
description	string	no	New plain-text description; re-runs summarization. At most 8192 bytes of UTF-8.
filters	IcpFilters	no	Optional structured filters that sharpen the plain-text profile.
filters.firm_types	array of enum: “operating_company”, “investment_adviser”, “broker_dealer”, “investment_fund”, “nonprofit”, “public_body”, “other”, “unknown”	no	Firm types to target.
filters.size_bands	array of enum: “micro”, “small”, “medium”, “large”, “enterprise”, “unknown”	no	Size bands to target.
filters.countries	array of string	no	Headquarters countries to target.
filters.exclude_countries	array of string	no	Headquarters countries to exclude.
filters.exclude_domains	array of string	no	Firms to exclude by domain (for example existing customers).
filters.event_types	array of enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	no	Event types that signal buying intent for this ICP.

UpdateKeyRequest

Fields of an API key to change.

Field	Type	Required	Description
name	string	no	New name.
scopes	array of enum: “decisions:write”, “index:read”, “outcomes:write”, “watches:manage”, “vendors:call”, “account:read”, “account:manage”, “keys:manage”	no	Replacement scopes. A key can only grant scopes the calling key holds itself. Audited as key_scopes_changed.
rate_limit_per_minute	integer	no	Requests per minute.
daily_spend_cap_usd	number or null	no	Daily spend cap; null removes it. US dollars, up to 6 decimals.
ip_allowlist	array of string (ipv4-cidr) or string (ipv6-cidr)	no	CIDR blocks the key may be used from; empty means anywhere.
expires_at	string or null (date-time)	no	Expiry; null removes it.

UpdateMemberRequest

Change a member’s role.

Field	Type	Required	Description
role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	The new role. Only an owner may grant or remove owner.

UpdateThresholdsRequest

Set or reset decision thresholds on an ICP profile.

Field	Type	Required	Description
thresholds	object	yes	Thresholds to change, by decision name.
thresholds.qualify_firm	number or null	no	New threshold for qualify_firm, or null to return to the calibrated default.
thresholds.score_signal	number or null	no	New threshold for score_signal, or null to return to the calibrated default.
thresholds.pick_person	number or null	no	New threshold for pick_person, or null to return to the calibrated default.
thresholds.triage_reply	number or null	no	New threshold for triage_reply, or null to return to the calibrated default.
thresholds.right_person	number or null	no	New threshold for right_person, or null to return to the calibrated default.
thresholds.should_send	number or null	no	New threshold for should_send, or null to return to the calibrated default.

UsageResponse

Usage over a window.

Field	Type	Required	Description
from	string (date)	yes	First day included.
to	string (date)	yes	Last day included.
group_by	enum: “day”, “project”, “key”, “decision”	yes	Grouping used.
rows	array of object	yes	One row per group.
rows[].calls	integer	yes	Calls made.
rows[].billed_calls	integer	yes	Calls billed (misses and errors are free).
rows[].decision_usd	number	yes	Decision charges. US dollars, up to 6 decimals.
rows[].vendor_usd	number	yes	Vendor pass-through charges. US dollars, up to 6 decimals.
rows[].total_usd	number	yes	Total charges. US dollars, up to 6 decimals.
rows[].group	string	yes	Group key: a date, project id, key id or decision name.
totals	object	yes	Totals over the window; equal to the ledger sums.
totals.calls	integer	yes	Calls made.
totals.billed_calls	integer	yes	Calls billed (misses and errors are free).
totals.decision_usd	number	yes	Decision charges. US dollars, up to 6 decimals.
totals.vendor_usd	number	yes	Vendor pass-through charges. US dollars, up to 6 decimals.
totals.total_usd	number	yes	Total charges. US dollars, up to 6 decimals.

VendorWebhookBody

The vendor’s webhook payload, unchanged. Its shape is defined by the vendor.

Type: object.

VerifySignupRequest

Complete sign-up with the emailed token.

Field	Type	Required	Description
token	string	yes	The token from the verification link.

VerifySignupResponse

The organization, project and first key.

Field	Type	Required	Description
org_id	string	yes	The new organization.
project_id	string	yes	Its default project.
key	CreatedApiKey	yes	A new API key with its secret (shown once).
key.id	string	yes	The key id.
key.project_id	string	yes	Project the key belongs to.
key.name	string	yes	Name.
key.environment	enum: “live”, “test”	yes	live or test.
key.prefix	string	yes	The key’s first characters, to recognize it.
key.scopes	array of enum: “decisions:write”, “index:read”, “outcomes:write”, “watches:manage”, “vendors:call”, “account:read”, “account:manage”, “keys:manage”	yes	Scopes granted.
key.status	enum: “active”, “rotating”, “revoked”, “expired”	yes	Lifecycle status.
key.rate_limit_per_minute	integer	yes	Requests per minute allowed.
key.daily_spend_cap_usd	number or null	yes	Daily spend cap, or null for none. US dollars, up to 6 decimals.
key.ip_allowlist	array of string	yes	CIDR blocks the key may be used from; empty means anywhere.
key.expires_at	string or null (date-time)	yes	Expiry, or null for none.
key.last_used_at	string or null (date-time)	yes	Last successful use, or null.
key.created_at	string (date-time)	yes	When the key was created.
key.secret	string	yes	The API key: vd_live_ or vd_test_ plus a base62 body. Shown once; store it now.
starter_credit_usd	number	yes	Starter credits granted. US dollars, up to 6 decimals.
balance_usd	number	yes	Balance after the grant. US dollars, up to 6 decimals.

Watch

A standing scored-event subscription.

Field	Type	Required	Description
id	string	yes	The watch id.
project_id	string	yes	Project the watch belongs to.
icp_id	string	yes	ICP profile events are scored for.
webhook_url	string (uri)	yes	Delivery endpoint.
min_p	number	yes	Minimum relevant delivered.
types	array of enum: “filing”, “registration”, “officer_change”, “ownership_change”, “lei_change”, “address_change”, “fund_raise”, “insider_trade”, “patent_filing”, “litigation”, “news_mention”, “repo_activity”, “hiring_aggregate”	yes	Event types watched.
status	enum: “pending_verification”, “active”, “paused”, “deleted”	yes	Lifecycle status.
created_at	string (date-time)	yes	When the watch was created.
updated_at	string (date-time)	yes	When the watch last changed.

WebhookChallenge

The registration challenge sent to a new webhook URL.

Field	Type	Required	Description
type	enum: “webhook.challenge”	yes	Payload type.
watch_id	string	yes	The watch being registered.
challenge	string	yes	Random string; respond 200 with {"challenge": <this value>} within 10 seconds.

WebhookReceipt

Acknowledgement of a vendor webhook.

Field	Type	Required	Description
received	enum: true	yes	The payload was verified and accepted.
duplicate	boolean	yes	True when this vendor event id was already processed.
outcome_ids	array of string	yes	Outcomes created from the payload; empty when it maps to none.